test

WBEMfor Solaris on Sun Developer's Guide

Part III Solaris WBEM Services

The Solaris WBEM Services software is Sun's implementation of WBEM on the Solaris operating environment. This software provides the following services:

Chapter 10 Installing Solaris WBEM Services

This section describes Solaris WBEM Services and explains how to install and remove it from your system. Topics covered include the following:

About Solaris WBEM Services

Solaris WBEM Services includes the following components:

CIM Object Manager

The Common Information Model (CIM) Object Manager manages CIM objects and routes object data. CIM Object Manager is a standard executable Java class file that is started automatically as part of the post-installation process. CIM objects are represented internally as Java classes. When an application uses the client API to request or update information about a managed object, the CIM Object Manager contacts either the appropriate provider for that object or the CIM Repository, the persistent storage mechanism.

Classes, properties, and methods handled by a provider have a Provider qualifier that identifies the provider to contact for the class. When the CIM Object Manager receives a request for a class that has a Provider qualifier, it routes the request to the specified provider. If no provider is specified, it routes the request to the persistent data storage, using the Java Naming and Directory Interface (JNDI).

The CIM Object Manager can be installed and run on one or more Solaris hosts. When a WBEM-enabled client connects to a CIM Object Manager, it gets a reference to the CIM Object Manager. The client can then perform WBEM operations using this reference.

Semantic and Syntactic Checking

CIM Object Manager performs syntactical and semantic checking. Syntactical checking refers to the ability to detect an error, such as a misplaced semicolon or a forgotten brace, in a line of code. Semantic checking refers to the ability to detect an error in the rules or logic of the program. The CIM Object Manager follows rules provided by the Common Information Model, and detects deviations from CIM rules in a WBEM application.

For example, CIM rules designate that only a key property can override another key property. Class A, which is assigned a key, cannot be overwritten by Class B because Class B is not assigned a key. In this case, CIM Object Manager returns a semantic error. 

Class A        
\\Define Class A 
{     
[Key]     int a;   
}    
Class B:A     
 \\Class B extends A  
{  
[overrides ("a", key (false)]   int b;   
}

Sun WBEM User Manager

Sun WBEM User Manager is a software application in which you can set user privileges to specific areas, called namespaces, where classes are stored. You can also delete namespaces and create new namespaces in Sun WBEM User Manager. For information about how to use Sun WBEM User Manager, see Chapter 12, Administering Security.

Solaris Provider

Solaris WBEM Services includes the Solaris Provider, a program that enables the CIM Object Manager to communicate with the Solaris operating environment. The Solaris Provider is defined in a set of files created in Managed Object Format (MOF). Collectively, these files are referred to as the Solaris Schema. They extend CIM classes for the Solaris environment by providing definitions of the classes that the CIM Object Manager and the Solaris environment use to communicate.

The MOF files that make up the Solaris Schema are located in /opt/SUNWconn/wbem/schema. You can view these files in a text editor of your choice. Solaris_Schema1.0.mof is the principal schema file. It contains pointers to the other files that make up the Solaris Schema in the order in which the files are compiled at installation.

During the installation of Solaris WBEM Services, the MOF compiler compiles standard CIM 2.1 MOF files into the CIM Object Manager. After installation, these compiled classes represent the resources on your system, such as processes, application software, CPU resources, and memory. Applications can then use the API to get, set, and otherwise manipulate the managed resources on any WBEM-enabled system.

In addition, Solaris WBEM Services includes the Solaris Schema, MOF files that further describe Solaris-specific resources, such as Solaris patches and installed software packages. The Solaris Schema extends the standard CIM Schema classes.

Other vendors who extend the standard CIM Schema also build on the base classes. The benefit of using this information model to manage systems is that an application can get and set the properties for any system resource (for example, process) on any CIM system. You can use the same API to get and set properties about a process or device on a Microsoft Windows 32 system, a Solaris system, a UNIX platform, or any other CIM-compliant platform.

Installation Prerequisites

Prior to installing the Solaris WBEM Services, ensure that Sun Directory Services (SDS) version 3.1 or a compatible version is installed. SDS is used for the CIM Repository.

Shared Packages

You can install Solaris WBEM Services as a product that runs on its own, or you can install both Solaris WBEM Services and the Sun WBEM SDK to be used interactively. Installing either product involves installing the product packages. The packages are compilations of the files, interfaces, and components of each product.

Solaris WBEM Services and the Sun WBEM SDK share some of the same packages. For example, both applications require the package named SUNWwbapi, that contains the Client APIs.

For information about Solaris WBEM Services packages and installation instructions, see the following section, "Installing Solaris WBEM Services". For information about Sun WBEM SDK packages and installation instructions, see Chapter 2, Installing the Sun WBEM SDK.

Installing Solaris WBEM Services

The following table describes the packages you need to install Solaris WBEM Services.

Table 10-1 Solaris WBEM Services Packages

Required Packages 

Package Name 

Title 

Description 

SUNWwbapi

Sun WBEM SDK - APIs 

Contains the client and provider APIs and additional functionality required to run Solaris WBEM Services and the Sun WBEM SDK. This package is provided with the Sun WBEM SDK. It is required by both products. 

SUNWwbcor

Solaris WBEM Services 

Contains Solaris WBEM Services components, including the MOF Compiler and the CIM Object Manager. 

SUNWwbxml

Solaris WBEM Services - XML Libraries 

Contains the XML libraries that enable conversion between XML and Managed Object Format (MOF). 

Optional Packages 

Package Name 

Title 

Description 

SUNWwbdoc

Solaris WBEM Services - Documentation 

Contains the WBEM Developer's Guide, which supports both Solaris WBEM Services and the Sun WBEM SDK. Although this package is provided with Solaris WBEM Services, it can be installed optionally to support either product.

Localized Packages 

Package Name 

Title 

Description 

SUNWxxwbs

Solaris WBEM Services - Localization 

Contains the localized version of Solaris WBEM Services. The xx is replaced by the character code that represents the particular language in which the application is localized. For example, the French version of Solaris WBEM Services is packaged in SUNWfrwbs.

How to Install Solaris WBEM Services

  1. Become root on your system by typing the following command: 

    % su

  2. Type the root password when you are prompted.

  3. Change directories to the location of the packages in your work environment.

  4. At the system prompt, type the following command to obtain a list of packages: 

    # pkgadd -d .

    The list of packages is displayed. You are prompted to select one or all packages.

  5. Type the number of the package you want to install.

    • Type 1 to install the SUNWwbapi package. It is important to install this package first because the other packages rely on the Sun WBEM APIs.

    • Type 2 to install the SUNWwbcor package, which installs Solaris WBEM Services.

      When the SUNWwbcor package installs, the installation routine prompts you to provide the Sun Directory Services (SDS) administration password. If you have already installed SDS prior to installing Solaris WBEM Services, type the SDS password at the prompt. If you have not previously installed SDS, type a password of your choice at the prompt to set the SDS password. When you are prompted to re-enter the password, type the password again at the prompt.

    • Type 7 to install the SUNWwbxml package, which installs the XML Libraries.

    • (Optional): Type 3 to install the SUNWwbdoc package, which installs this guide.

    As each package installs, its contents are listed for you to view. When the installation is complete, you are notified with the message: Installation of package_name was successful.

  6. When you have finished installing the packages, type q to exit the package installation routine.

  7. Type exit at the system prompt to exit root.

Configuring After Installing in Solaris 7

When you install Solaris WBEM Services as part of a Solaris Easy Access Server 3.0 installation in Solaris 7, you may not be prompted to enter a password for the Sun Directory Services (SDS) administrative account. If you did not enter this password during the installation, run the wbemconfig script as described in the following procedure to start SDS and configure Solaris WBEM Services. The wbemconfig script completes the following tasks:

How to Configure Your Environment After Installation

  1. Become root on your system by typing the following command: 

    % su

  2. Type the root password when you are prompted.

  3. Run the wbemconfig script using the following command: 

    # /opt/SUNWconn/wbem/bin/wbemconfig

  4. When prompted, type a password of your choice to be set as the SDS administrative account password.

    The wbemconfig script runs. SDS starts followed by the CIM Object Manager. The MOF Compiler starts and compiles the CIM and Solaris Schema files.

Uninstalling Solaris WBEM Services

When you want to uninstall Solaris WBEM Services from your computer, you remove the packages. When you remove the Solaris WBEM Services packages, not all files that make up your WBEM installation are removed. If Sun WBEM SDK is installed, none of its associated packages are removed. For information about removing Sun WBEM SDK, see "Uninstalling the Sun WBEM SDK" in Chapter 2, Installing the Sun WBEM SDK.

If you uninstall both the Sun WBEM SDK and Solaris WBEM Services, the LDAP schema and data files remain installed. You can remove these files, and the subdirectories that contain them, from the path /opt/SUNWconn/ldap. However, if you remove the LDAP data, you may encounter errors in other applications that require the data. Also, if you remove the LDAP data, you will need to re-install it if you decide to re-install the Sun WBEM SDK or Solaris WBEM Services at a later date.

How to Uninstall Solaris WBEM Services

  1. Become root on your system by typing the following command: 

    % su

  2. Type the root password at the Password prompt.

  3. Type the following command at the system prompt to remove a package: 

    # pkgrm package_name

    where package_name is replaced by the name of the package that you want to remove.

  4. Type y when you are prompted with the question: "Do you want to remove this package?"

    You can remove the following packages in any order:

    • SUNWwbcor

    • SUNWwbxml

      SUNWwbdoc

    Be sure to remove the SUNWwbapi package last because all other packages rely on it.

    When a package has been removed successfully, the following message is displayed.

    Removal of package_name was successful

  5. Type the pkgrm command at the system prompt for each package you want to remove.

  6. Type exit to exit root and return to your system prompt when you have finished removing packages.

Chapter 11 CIM Object Manager

When Solaris WBEM Services is installed, the CIM Object Manager starts automatically and runs continuously. It restarts automatically between system sessions or after a power outage. At times, such as if you change a provider program, you have to manually restart the CIM Object Manager.

Note -

If you change a provider program, you must stop and restart the CIM Object Manager before you can use the updated provider.

This chapter describes how and when to stop and restart the CIM Object Manager. The following topics are covered.

About CIM Object Manager

During the installation of Solaris WBEM Services, the CIM Object Manager starts automatically. Generally, you do not need to stop the CIM Object Manager. However, if you change a provider program, you must stop and restart the CIM Object Manager before you can use the updated provider.

Solaris WBEM Services provides one way to stop the CIM Object Manager and two ways to restart it. Use the init.wbem command to stop the CIM Object Manager. Use the init.wbem command to restart the CIM Object Manager between sessions, or use the cimom command to restart the CIM Object Manager on a specific host or view the version of the CIM Object Manager.

To stop a running CIM Object Manager or restart a stopped CIM Object Manager, you must be logged in as root. For information about stopping the CIM Object Manager, see "Stopping the CIM Object Manager". For information about restarting the CIM Object Manager after it has been stopped, see "Restarting the CIM Object Manager".

The init.wbem Command

The init.wbem restarts the CIM Object Manager between system sessions. The init.wbem command can also be used to stop the CIM Object Manager.

Location of the init.wbem Command

The init.wbem command is located in the following path: /etc/init.d/init.wbem.

Syntax of the init.wbem Command

The init.wbem command uses only two parameters:

Parameter 

Description 

stop 

Enables you to stop the CIM Object Manager 

start 

Enables you to restart the CIM Object Manager 

The syntax of the init.wbem command is:

The cimom Command

Use the cimom command to start the CIM Object Manager when you want to obtain or specify additional information, such as the host that contains a CIM Repository in which you want your objects to be stored. The cimom command uses parameters that enable you to specify characteristics of the CIM Object Manager.

Location of the cimom Command

By default, the cimom command is located in the following path: /opt/SUNWconn/wbem/bin/

Syntax of the cimom Command

The cimom command uses the following three parameters.

Parameter 

Description 
-help

Causes a man page to display with information about the cimom command and parameters.
-sdatabase_server

Enables you to specify a server installed with a CIM Repository. This parameter provides control over where your CIM objects are stored. 
-version

Causes the build version of the CIM Object Manager to be displayed.  

The syntax of the cimom command is: cimom [parameter] [modifier]

where [parameter] is any of the parameters shown in the preceding table, and [modifier] is the additional information that is required by a parameter. For example in the command cimom -s hopskotch, -s is the [parameter] and hopskotch is the [modifier] that indicates the name of the server on which the CIM Repository is located.

Stopping the CIM Object Manager

Use the following procedure to stop the CIM Object Manager.

How to Stop the CIM Object Manager

  1. Become root on your system by typing the following command at the system prompt: 

    % su

  2. Type the root password when you are prompted.

  3. Change directories to the location of the init.wbem command by typing the following command: 

    # cd /etc/init.d/

  4. Stop the CIM Object Manager by typing the following command: 

    # ./init.wbem stop

    The CIM Object Manager stops.

Restarting the CIM Object Manager

You can restart the CIM Object Manager using the init.wbem command or the cimom command, depending on how you want to restart. If you want to restart the CIM Object Manager on the default host, use the init.wbem command. If you want to restart the CIM Object Manager on another host, use the cimom command. Using the cimom command, you can also view the version of the CIM Object Manager.

How to Restart the CIM Object Manager Using Default Settings

  1. Become root on your system by typing the following command at the system prompt: 

    % su

  2. Type the root password when you are prompted.

  3. Change directories to the location of the init.wbem command by typing the following command:

    # cd /etc/init.d/

  4. Restart the CIM Object Manager by typing the following command:

    # ./init.wbem start

    The CIM Object Manager starts.

How to Restart the CIM Object Manager and Specify a Host

  1. Become root on your system by typing the following command at the system prompt:

    % su

  2. Type the root password when you are prompted.

  3. Change directories to the location of the cimom command by typing the following command: 

    # cd /opt/SUNWconn/wbem/bin

  4. Restart the CIM Object Manager and specify a host by typing the following command: 

    # cimom -s server_name

    where server_name is the name of a specific host running a CIM Object Manager Repository.

    The CIM Object Manager resumes running.

Error Messages Generated by the CIM Object Manager

The CIM Object Manager generates error messages to indicate incorrect MOF syntax and semantics. The same error messages are generated by the MOF Compiler and the CIM Workshop. To view the error messages and their meanings, see Chapter 9, Error Messages.

Chapter 12 Administering Security

This chapter describes the security features enforced by the CIM Object Manager, including the following topics:

Overview

The CIM Object Manager validates a user's login information for the machine on which the CIM Object Manager is running. A validated user is granted some form of controlled access to the entire Common Information Model (CIM) Schema. The CIM Object Manager does not provide security for system resources such as individual classes and instances. However, the CIM Object Manager does allow control of global permissions on namespace and access control on a per-user basis.

All security-related information is represented by instances of security classes located in the root\Security namespace and must remain there permanently.

The following security features protect access to CIM objects on a WBEM-enabled system:

Authentication

When a user logs in and enters a user name and password, the client encrypts the password and sends the encrypted password to the CIM Object Manager. When the user is authenticated, the CIM Object Manager sets up a client session. All subsequent operations occur within that secure client session.

Authorization

The CIM Object Manager creates two user accounts:

Once 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 the application or any of its tasks. The CIM Object Manager supports capability-based authorization, which allows an administrator to assign read and write access to specific users. These authorizations are added to existing Solaris user accounts.

Note -

We do not recommend logging in as root because successful login to the root account depends on how name services (for example, DNS, NIS, or NIS+) are set up on your system.

Using the Sun WBEM User Manager to Set Access Control

The Sun WBEM User Manager allows administrators to add and delete authorized users and to set their access privileges. Use this application to manage user authentication and access to CIM objects on a WBEM-enabled system. A user must have a Solaris user account.

You can set access privileges on individual users, on namespaces, or on both. When you add a user, you select a namespace. This action grants the user read access to CIM objects in the selected namespace.

Administrators are users who are logged in to the WBEM administrative account, wbemadmin. Administrators can set the following types of access to CIM objects:

How to Start Sun WBEM User Manager

  1. In a command window, type the command:

    % /opt/SUNWconn/wbem/bin/cimadmin

    The Sun WBEM User Manager is started. The User Manager and Login dialog boxes are displayed at the same time. The Login dialog box shows the name of the current host. Context-help information is available on the fields in the dialog box.

  2. In the Login dialog box, do the following:

    • In the Host Name field, type the name of a host running the CIM Object Manager.

    • In the User Name field, type wbemadmin. You must log in to the administrative account to administer WBEM user accounts.

    • In the Password field, type the password for the wbemadmin account.

  3. Click OK.

    The User Manager dialog box opens with a list of users and their access rights to WBEM objects within the namespaces on the current host.

How to Grant Default Access Rights to a User

  1. Start Sun WBEM User Manager.

  2. In the Users Access portion of the dialog box, click Add.

    A dialog box opens that lists the available namespaces.

  3. Type the name of a Solaris user account in the User Name text entry field.

  4. Select a namespace from the listed namespaces.

  5. Click OK.

    This action grants this user read access to CIM objects in the selected namespace. The user is added to the User Manager dialog box.

  6. Click OK again to close the User Manager dialog box.

How to Change Access Rights for a User

  1. Start Sun WBEM User Manager.

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

  3. To grant the user read-only access, click the Read check box. To grant the user write access, click the Write check box.

  4. Click OK.

How to Remove Access Rights for a User

  1. Start Sun WBEM User Manager.

  2. In the Users Access portion of the dialog box, select the user name for which you want to remove access rights.

  3. Click Delete to delete the user's access rights to the namespace.

    A confirmation dialog box asks you to confirm your decision to delete the user's access rights. Click OK to confirm.

  4. Click OK again to close the User Manager dialog box.

How to Set Access Rights for a Namespace

  1. Start Sun WBEM User Manager.

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

    A dialog box opens that lists the available namespaces.

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

    By default, users have read-only access to a namespace.

  4. To allow no access to the namespace, make sure the Read and Write check boxes are not selected. To allow write access, click the Write check box. To allow read access, click the Read check box.

  5. Click OK to close the User Manager dialog box.

How to Remove Access Rights for a Namespace

  1. Start Sun WBEM User Manager.

  2. In the Namespace Access portion of the dialog box, select the namespace for which you want to remove access control, and then click Delete.

    Access control is removed from the namespace, and the namespace is removed from the list of namespaces on the User Manager dialog box.

  3. Click OK to close the User Manager dialog box.

Using the 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. During installation, the MOF compiler compiles the security classes defined in the Solaris_Acl1.0.mof file into the /root/Security namespace. The Solaris_Acl1.0.mof file defines the following classes:

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 (ACL) 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 with a default value r (read only).

You can set the capability property to any of the following values for access privileges.

 Access Right Description

r

Read 

rw

Read and Write 

w

Write 

none

No access 

The Solaris_UserAcl class defines the following two key properties. Only one instance of the namespace-username ACL pair can exist in a namespace.

 Property Data Type Purpose

nspace 

string 

Identifies the namespace to which this ACL applies.  

username 

string 

Identifies the user to which this ACL applies. 

How to Set Access Control on a User

  1. Create an instance of the Solaris_UserAcl class. For example:

    // Get the Solaris_UserAcl class
cimclass = cc.getClass(newCIMObjectPath("Solaris_UserAcl");
 
// Create a new instance of the Solaris_UserAcl class
ci = cimclass.newInstance();

  2. Set the capability property to the desired access rights. For example:

    /* Change the access rights (capability) to read/write
for user Guest on objects in the root\molly namespace.
ci.updatePropertyValue("capability",new CIMValue("rw"));  
ci.updatePropertyValue("nspace",new CIMValue("root\molly"));
ci.updatePropertyValue("username",new CIMValue("guest"));

  3. Update the instance. For example:

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

The Solaris_NamespaceAcl Class

The Solaris_NamespaceAcl extends the Solaris_Acl base class, from which it inherits the string property capability with a default value 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 applies. Only one instance of the namespace ACL can exist in a namespace. 

How to Set Access Control on a Namespace

  1. Create an instance of the Solaris_namespaceAcl class. For example:

    // Get the Solaris_namespaceAcl class
cimclass = cc.getClass(newCIMObjectPath("Solaris_namespaceAcl");
 
// Create a new instance of the Solaris_namespaceAcl class
ci = cimclass.newInstance();

  2. Set the capability property to the desired access rights. For example:

    /* Change the access rights (capability) to read/write
to the root\molly namespace. */
ci.updatePropertyValue("capability",new CIMValue("rw"));  
ci.updatePropertyValue("nspace",new CIMValue("root\molly"));

  3. Update the instance. For example:

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

Error Messages

For a description of error messages, see Chapter 9, Error Messages.

Chapter 13 Logging Events

Logging is a service that enables WBEM administrators to track uncommon events to determine how they occurred. This chapter covers the following topics:

About Logging

The logging service records all actions completed by Solaris WBEM Services or Sun WBEM SDK components. 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 WBEM administrator can check the log record to trace the cause of the occurrence.

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

You can set up logging for applications and providers that you develop for the WBEM environment. For information, see "Using the APIs to Enable Logging". You can also view log data in CIM WorkShop for administration purposes or to debug the logging functionality that you develop for applications.

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/opt/SUNWconn/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, such as wbem_log.1, is the most recently-saved version. A log file appended with a .2 is the next oldest version. Larger file extensions, for example, wbem_log.16, indicate older versions of the file. Previous versions of the log file and the most recent version co-exist as an archive in /var/opt/SUNWconn/wbem/log.

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

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:

When you want to specify any of these attributes for an application that writes data to a log file, you create a new instance of Solaris_LogServiceProperties and set the values of its associated properties.

Log File Format

The logging service provides three general types of log files: application logs, system logs, and security logs. Log records may be informational, or may record data derived from errors or warnings. A standard set of fields are 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 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 set the values of any of the following fields in your log files:

Log Classes

Logging uses two Solaris Schema classes: Solaris_LogRecord and Solaris_LogService.

Solaris_LogRecord

Solaris_LogRecord is defined in Solaris_Core1.0.mof 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 of your choice. The Solaris_Core1.0.mof file is located in /opt/SUNWconn/wbem/schema.

Solaris_LogRecord 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 writeable 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.

Solaris_LogService

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:

You can view the definition of Solaris_LogService in the Solaris_Core1.0.mof file by opening the file in a text editor of your choice. The Solaris_Core1.0.mof file is located in /opt/SUNWconn/wbem/schema.

Viewing Log Data

If your application has been enabled to log data in response to events, you can view the generated data in CIM Workshop.

How to View Log Data

  1. In CIM Workshop, select solaris_logrecord in the class inheritance tree.

  2. Click Action->Instances.

  3. In the left side of the Instances for Solaris_LogRecord window, click the instance that was generated by your application.

    In the right side of the Instances for Solaris_LogRecord window, the fields of the log file are displayed as properties. Values for each property are provided in the Values column.

Using the APIs to Enable Logging

Currently, you can view log file content in CIM Workshop. 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 or read data from a log file to your log viewer.

Writing Data to a Log File

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

How to Create an Instance of Solaris_LogRecord to Write Data

  1. Import all necessary java.rmi classes.

    Example 13-1 Importing Classes

    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 public class CreateLog and the following values:

    • CIMClient value

    • CIMObjectPath value

    • CIMNameSpace value

    Example 13-2 Declaring the CreateLog Class and Values

    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.

    Example 13-3 Specifying the Vector of Properties and their Values

    Vector keys = new Vector();  		
CIMProperty logsvcKey = new CIMProperty("RecordID"); 		
logsvcKey.setValue(new CIMValue(new Integer(0))); 		
keys.addElement(logsvcKey); 		
logsvcKey = new CIMProperty("RecordHashCode"); 		
logsvcKey.setValue(new CIMValue(new Integer(0))); 		
keys.addElement(logsvcKey); 		
logsvcKey = new CIMProperty("Filename"); 		
logsvcKey.setValue(new CIMValue("some_file")); 		
keys.addElement(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); 		
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 CIMObject Path for the log record.

    Example 13-4 Declaring the New Instance of CIMObjectPath

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

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

    Example 13-5 Setting the Instance and Properties

    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.

    Example 13-6 Closing the Session

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

Reading Data from a Log File

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

How to Get an Instance of Solaris_LogRecord and Read Data

  1. Import all necessary java.rmi classes.

    Example 13-7 Importing Classes

    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.

    Example 13-8 Declaring the ReadLog Class

    public class ReadLog 
    {
    public static void main(String args[]) throws 
    CIMException 
    {
    if ( args.length != 3) 
    {
    System.out.println("Usage: ReadLog host username 
    password"); 
	    System.exit(1);

  3. Set client, object path, and namespace values of the ReadLog class.

    Example 13-9 

    	} 	
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 instances of Solaris_LogRecord.

    Example 13-10 Enumerating Instances

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

  5. Send property values to an output device.

    Example 13-11 Sending Property Values

    	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 = (((Integer)ci.getProperty("category").
      getValue().getValue()).intValue());
			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()).intValue());
			if (severity == 0)
				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.

    Example 13-12 Returning an Error Message

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

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

    Example 13-13 Closing the Session

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