pegasus/Attic/readme.txt - diff

Return to readme.txt CVS log

Up to [Pegasus] / pegasus / Attic

Diff for /pegasus/Attic/readme.txt between version 1.10 and 1.16.2.1

version 1.10, 2003/05/21 11:32:22

version 1.16.2.1, 2004/03/09 21:52:54

Line 1

Pegasus - A Manageability Services Broker for the DMTF CIM/WBEM Standards

OpenPegasus - A Manageability Services Broker for the DMTF CIM/WBEM Standards

Author: Mike Brasher, Karl Schopmeyer

Tagline: Pegasus is an object manager for DMTF CIM objects written in C++

Tagline: OpenPegasus is an object manager for DMTF CIM objects written in C++

and supported by The Open Group

Overview:

STATUS: Revised October 2003 to match Pegasus release 2.3

NOTE: Obsolete. See readme.html

Contents:

=========

1. Overview

2. Availability of Pegasus

3. Pegasus major components

4. Pegasus Dependencies

5. The Pegasus Directory Structure

6. Installation

7. Building Pegasus

8. Populate the Repository

9. The MU Utility

10. Notes about Building Pegasus on Linux

11. Notes on building Pegasus with SSL

12. Building Pegasus on Windows 2000 or Windows XP With Microsoft Visual C++

13. Installing the Pegasus HTML Test Client

14. Development with Pegasus and Pegasus Tools

15. Commands

16. Creating SSL certifications.

17. Configuring Pegasus to use SSL

18. Testing with ICU enabled

19. Documentation

20. Participate

1. Overview:

============

OpenPegasus (also refered to as Pegasus):

Pegasus is an open-source object manager for DMTF CIM objects. It is written

in C++ and includes the Object manager, a set of defined interfaces, and SDKs

for both client, providers, and services extensions. It is maintained

Line 24

Line 57

(LICENSE) of this release. This licensing is intended to support as wide a

distribution as possible with minimal demands on the users.

This distribution represnts a snapshot of the current work. Currently Pegasus

This distribution represents a snapshot of the current work. Currently Pegasus

is in phase 1 of a multiphase development project. This snapshot is primarily

for developers and for evaluation of the project.

Line 40

Line 73

In addition, the roadmap for Pegasus and further information on the project is

available on The Opengroup Pegasus WEB Site.

http://www.opengroup.org/MSB

http://www.openpegasus.org

Availability of Pegasus:

========================

Pegasus is distributed as open source. Today the distribution is limited

2. Availability of Pegasus:

because we want to reach a predefined level of development before making the

============================

project publically available. The move from limited to open distribution will

be a decision of the Pegasus development team and The Open Group and should

occur before March 2001.

To get on the distribution list for Pegasus today, send an email to

Pegasus is distributed as open source. The distribution is available via

CVS and snapshot images in tar and zip file formats.

m.kirk@opengroup.org

The source code from CVS can be found at the following Open Group CVS server;

cvs.opengroup.org:/cvs/MSB

k.schopmeyer@opengroup.org

using the password authenticating server option (pserve).

Anonymous access for read is with the name and password "anon" as follows:

%export CVSROOT=:pserver:anon@cvs.opengroup.org:/cvs/MSB

%cvs login

When requested, enter the password "anon"

The source tree is in the directory pegasus. To check out the complete Pegasus

source tree just type:

cvs co pegasus

A Pegasus directory will be created under the current directory and populated

with the complete source tree and documentation. To get the latest updates

after a checkout just type this from Pegasus root:

cvs update -d

Active contributors to Pegasus have write access to the CVS repository.

If you are interested in contributing back to the Pegasus project,

(i.e. write (checkin) access to CVS) please request access from either

Martin Kirk (m.kirk@opengroup.org) or Karl Schopmeyer (k.schopmeyer@opengroup.org).

Pegasus Major Components:

=========================

3. Pegasus Major Components:

=============================

The major components of Pegasus are:

Line 70

Line 124

interface and a simple file based class repository. It also includes

an instance repository. Note that these repository were created for

functionality, not efficieny. It is expected that they will be replaced

with other implementations of the respository function as the need arrses.

with other implementations of the respository function as the need arises.

Pegasus Client SDK - Tools for building Pegasus clients based on the Pegasus

C++ interfaces and using the WBEM HTTP/XML protocols or directly

Line 82

Line 136

Pegasus HTML Test Client - To aid in testing we created a test client for

Pegasus that uses a WEB server (ex. Apache) with a set of CGI modules and

HTML to allow the entry of Pegasus operations from a WEB browser as forms

and the recept of the response as WEB pages. This has proven useful as a

and the receipt of the response as WEB pages. This has proven useful as a

test tool and can be used for a wide variety of demonstrations.

Pegasus Provider SDK - Tools for build Pegasus clients based on the Pegasus

Pegasus Provider SDK - Tools for building Pegasus providers using the Pegasus

C++ interfaces.

Pegasus Providers - A sampling of key providers to make the environment

Pegasus Providers - Providers to illustrate the use of Pegasus services including

complete as well as test providers and demonstration providers for the

providers for test and demonstration.

Pegasus.

Pegasus Service Extensions - Future (version 1.0)

Pegasus Service Extensions - Common services for use by other Pegasus

components to extend Pegasus capabilites.

Pegasus MOF Compiler - FA standalone compiler for MOF files that can be used

to install MOF into the Pegasus schema repository and also to check syntax

to install MOF into the Pegasus schema repository and also to check syntax.

There is also a tool to extract the MOF from the repository.

Pegasus Dependencies:

=====================

4. Pegasus Dependencies:

=========================

We have worked to minimize the dependence of Pegasus on other software

packages and tools. Currently Pegasus has the following dependencies

packages and tools. Currently Pegasus has the following dependencies:

1. GNUMAKE - To simplify the building of Pegasus across multiple platforms we

have standardized on a set of build tools including: GNUMAKE. We are using

GNUAKE 4.79.1 successfully both in Windows and Linux environments.

GNUMAKE 3.79.1 successfully both in Windows and Linux environments.

GNUMAKE is available from

http://www.gnu.org

ATTN: I think we need to make our version available on the TOG site.

COMMENT: Unless other users of Pegasus demand it, we will NOT create

any build environment for Pegasus that does not require GNUMAKE (e.g.,

Visual C++). We are open to other developers who want to contribute

other build structures for particular environments.

2. MU.EXE - To minimize the difference between Linux and Windows for GUNMAKE,

2. MU.EXE - To minimize the difference between Linux and Windows for GNUMAKE,

we have created a utility called MU.exe. This utility is required for

Pegasus make with Windows environment. It is provided as an alternative to

Pegasus make with ONLY Windows environment. It is provided as an alternative to

requiring a number of UNIX utilities (SH, RM, etc.) on the windows platform

and effectively provides the functions of these utilities that GNUMAKE

needs. MU is not required on UNIX or LINUX platforms.

Line 130

Line 180

in the directory src/utils/MU with its own make file. You must compile MU

before you initiate the Pegausu make.

NOTE: We will make a copy of the binary available on the MSB WEB site to

NOTE: A copy of the binary is made available as a zip file on the Pegasus

eliminate the requirement to build this utility.

WEB site.

3. FLEX and BISON - These tools were used to develop the compiler, anybody

Again, MU is used ONLY if you are using Windows.

intending to recompile the compiler from scratch will be required to have

these tools.

3. FLEX and BISON - These tools were used to develop the MOF compiler and WQL

parser. Anybody intending to recompile the compiler or parser from scratch

will be required to have these tools. They are only required if changes need

to be made to the files for parsing and compiling.

4. DOC++ - The Pegasus documentation is taken from a combination of text files

and the Pegasus header files themselves. This documentation is formatted

Line 143

Line 197

be recreated but we expect that only the core team will be recreating

documentaiton.

The Pegasus Directory Structure

===============================

5. The Pegasus Directory Structure

===================================

Pegasus is distributed as a complete directory structure that should be

installed either from one of the snapshots or from CVS.

Line 153

Line 208

Pegasus Pegasus Root directory

build Default destination for runtime if PEGASUS_HOME

is not specified. Does not exist if PEGASUS_HOME

is specified

cgi Source for the Pegasus WEB Based Test client

cgi-bin CGI Directories for WEB demonstration.

This directory is normally empty but can

Line 166

Line 215

from cgi.

htdocs HTML Pages for Pegasus WEB emonstration

doc Miscellaneous Pegasus Documents.

DevManual Source and build files for developes manual

DevManual Source and build files for developers' manual

mak General make files (used by other makes)

src All Pegasus Source Files

ACEExample Test directrory with examples of the use of ACE

ACEExample Test directrory with examples of the use of ACE (obsolete).

Clients Source for various test clients and client SDK

CGICLIENT Pegasus test client that uses a WEB browser

JAVA Java Client support modules

Pegasus

Client Pegasus Client API Tests

depends

tests

Common Pegasus Common Functions (C++ source and headers

tests Test programs for the common functions

Compiler Pegasus MOF compiler

Config TBD

Consumer TBD

ControlProvidersImplementation of Pegasus internal providers

ExportClient TBD

ExportServer TBD

Handler TBD

HandlerService TBD

IndicationService TBD

Listener TBD

Protocol Pegasus Client HTTP/XML Protocol Modules

depends

Provider Pegasus Provider interface functions

Repository Pegasus Repository Interfaces and Simple

ProviderManager Provider Manager service that manages providers

Repository

ProviderManager2Pluggable Provider Manager service

Repository Pegasus Repository Interfaces and Simple Repository

tests Tests for Repository Functions

Security TBD

Server Pegasus Server Modules

WQL TBD

Providers Pegasus test and required providers

generic TBD this and following

Utils

IndicationConsumer

Linux

ManaedSystem

slp

statistic

sample

testproviders

Server Pegasus executable build

slp

StandardIncludes

tools MU and other utilities written for Pegasus support

Unsupported Code that is made available but is not supported or included

in the normal make.

WMIMapper Pegasus implementation that implements mapping to Microsoft

WMI objects.

Runtime Directories

$PEGASUS_HOME$ Home directory for runtime. All compiler, linker

Line 197

Line 275

Manual HTML output of the Pegasus Manual

lib Destination for Pegasus LIB modules

obj Destination for object modules

Repository This Directory containes the created repository

repository This Directory contains the created repository

In the near future we will add directories for:

6. Installation

================

Service Extensions

Pegasus today is provided only as a source distribution.

Servers - Today the server executable is built from /server/test.

Installation:

To install Pegasus, you must check it out using CVS (Common Version System)

=============

or download the snapshot. You download, compile, and use it.

Pegasus today is provided only as a source distribution. You download compile

For the snapshot, the installation of Pegasus involves expanding the snapshot

and use it. Pegasus currently compiles and runs under Linux, AIX, HPUX,

distribution files, building the runtime, the test files and test clients, and

Windows NT, and Windows 2000.

building the repository.

The installation of Pegasus involves expanding the snapshot distribution

files, building the runtime, the test files and test clients, and building the

repository.

Building Pegasus:

=================

7. Building Pegasus

=====================

1. Check that you have requisite programs (listed in Pegasus Dependencies).

These include GNU Make, MU.EXE, Flex, and Bison

These include GNU Make, MU.EXE (if using Windows), Flex, and Bison (Flex

and Bison only required if changes will be made to the MOF compiler or WQL

parser).

Be sure these are on your path.

2. Define the following two environment variables:

2. Define the following three environment variables:

PEGASUS_ROOT - this should be the "pegasus" directory you've pulled from CVS

PEGASUS_HOME - to point to a directory to contain output binary files

(e.g., set it to $HOME/pegasus_home).

(e.g., set it to $HOME/pegasus_home). Then the output will go into

$HOME/pegasus_home/bin and $HOME/pegasus_home/lib

PEGASUS_PLATFORM - this must be set to a supported platform identifier.

The following are supported:

WIN32_IX86_MSVC

LINUX_IX86_GNU

AIX_RS_IBMCXX

HPUX_PARISC_ACC

ZOS_ZSERIES_IBM

This identifier has the following form:

<Operating-System>_<Architecture>_<Compiler>

For example (Linux on IA32 platform using the GNU Compiler):

LINUX_IX86_GNU

For a complete list, refer to the platform_ make files found in directory

pegasus/mak

Note: if you plan on doing parallel builds, you might consider setting

PEGASUS_HOME to something like this:

Line 254

Line 335

and

Placd $PEGASUS_HOME/lib on your LD_LIBRARY_PATH (for Unix only).

Place $PEGASUS_HOME/lib on your LD_LIBRARY_PATH (for Unix only).

For RedHat/SuSE/UL, edit /etc/ld.so.conf and add $PEGASUS_HOME/lib

4. Now change to the root of the Pegasus distrubution and type "make"

4. Change to the root of the Pegasus distrubution and type "make"

(where make referes to GNU make).

(where make refers to GNU make).

5. Then create the repository, which is needed for some test cases -

5. Then create the repository, which is needed to serve data.

"make repository"

6. To test the build type "make tests".

Line 276

Line 358

The Pegasus Client server tests are executed separately from the above because

they require the initiation of separate process for the Pegasus server and

Pegasus client. These tests can be executed as follows:

Pegasus client. To execute these tests please refer to the scripts in

pegasus/mak/BuildMakefile - refer to the prestarttests and poststarttests.

ATTN: Add the procedure for Client/Server Test start here.

For information on particular installation characteristics, tools, etc. for

each platform see the appropriate sections below:

Line 286

Line 367

Generally the build commands are as follows:

1. There is a Makefile in the Pegasus root directory. Simply executing

make in the Pegasus root directory will make everything. "Make rebuild"

make in the Pegasus root directory will make everything. "make rebuild"

will clean and rebuild everything. The "make rebuild" will also populate

the repository with the current CIM Schemas.

Line 305

Line 386

Running "make -s tests" suppresses extraneous output such as the

enter/leave directory messages.

4. "Make Clean" removes all object and library files from the structure.

4. "make clean" removes all object and library files from the structure.

5. A new build system has been added to Pegasus where a new CVS checkout is done,

built, and tests are run. Do it by: "make -f mak/BuildMakefile cleanbuild"

8. Populate the Repository

===========================

The MU Utility

Before using Pegasus you must populate the repository with the providers. The makefile

==============

does it all for you, but in case you are wondering what it does or how to do it

manually:

1. Register the MOF (Managed Object Format) file describing the skeleton of the object.

2. Register a second MOF which only points out which lib*.so file to be loaded when a

specific object is activated.

This is done automatically for the providers included in Pegasus by doing:

make repository.

The 'make repository' in pegasus/Schemas does three things

Runs MOF compiler (cimmofl) on:

-Schema v2.7

Generates the CIM Schema v2.7 in the repository (skeleton of CIM objects)

-PG_InterOp

Internal to Pegasus schema for operating (shutdown, add users, etc)

CIM_Indication�s (SNMP, Events, Alert, Threshold, etc)

-PG_ManagedSystem

Registers included CIM Providers (libOSProvider.so, libDNSProvider.so, � )

in Pegasus (which are located in src/Providers)

For more information about using the MOF compiler, refer to user's manual on the

openpegasus.org.

9. The MU Utility

===================

In order to provide a consistent build structure across multiple platforms, we

developed a small utility to provide a consistent set of small utilities

Line 335

Line 450

MU is required to build under the Windows environment.MU is available as part

of the distribution of Pegasus.

Notes about Building Pegasus on Linux:

======================================

ATTN: put something here (but only what is not mentioned above).

10. Notes about Building Pegasus on Linux

===========================================

No problem. Just make sure you have the environment variables set.

Building Pegasus on NT or Windows 2000 With Microsoft Visual C++

11. Notes about Building Pegasus with SSL

================================================================

==========================================

Today we build Pegasus on Windows NT using a set of make files contained

To build with SSL you need the OpenSSL libraries and header files. Make sure

in the source distribution, the Microsoft compilers (tested so far with

you have them in a standard directory so Pegasus can find them. If that's not

versions 5 and 6) and the GNUMAKE make utility. The following is the basic

the case, set the environment varialble OPENSSL_HOME= to point where your OpenSSL

set up steps for the

installation is.

Setup the environment variables and path for the Micrososft Visual C

compiler. Typically this can be done by running the VCVARS32.BAT file

supplied with Microsoft Visual C++. (contained in the same directory

as cl.exe).

Installing the Pegasus HTML Test Client:

Also have the PEGASUS_HAS_SSL=yes variable set. Then just run 'make' in Pegasus

========================================

directory and you will have Pegasus with SSL enabled. See section "Creating SSL

certificates" for more information of how to use SSL.

12. Building Pegasus on Windows 2000 (SP3 or later recommended) or Windows XP

With Microsoft Visual C++

======================================================================

Today we build Pegasus on Windows using a set of make files contained

in the source distribution, the Microsoft compilers (DevStudio 5.x is not

supported, Visual Studio 6.0, SP5 supported) and the GNUMAKE make utility.The

following is the basic setup steps for the environment.

Setup the environment variables and path for the Micrososft Visual C compiler.

Typically this can be done by running the VCVARS32.BAT file supplied with

Microsoft Visual C++. (contained in the same directory as cl.exe).

For Windows, try the following for an example environment:

REM call the standard Microsoft .bat for VC 6 setup.

call 'C:/Program Files/Microsoft Visual Studio/VC98/Bin/Vcvars32.bat'

REM Set debug to something if you want compile in debug mode

set PEGASUS_DEBUG=true

REM set PEGASUS_ROOT to top of source tree

set PEGASUS_ROOT=C:/cimom/pegasus

REM set PEGASUS_HOME to where you want repository and executables

set PEGASUS_HOME=%PEGASUS_ROOT%

REM setup the path to the runtime files.

set path=%path%;%PEGASUS_HOME%/bin

13. Installing the Pegasus HTML Test Client:

=============================================

This is a separate test tool that allows Pegasus requests to be initiated from

any WEB browser and that uses a WEB browser, CGI scritps and HTML pages for

Line 362

Line 506

instructions for setting up this environment are maintained in a separate

readme in the CGI directory.

Development with Pegasus and Pegasus Tools:

===========================================

14. Development with Pegasus and Pegasus Tools:

================================================

ATTN: This section needs to be completed. It should reference the more

complete documentation

ATTN: Write about providers?

15. Commands:

=============

The manpages for each of the commands are in rpm/manLinux/man1.Z directory (on CVS)

Documentation:

To see simple help for each of the commands, use the "-h" flag.

==============

Examples:

bin/cimserver �s (Shuts it down)

bin/cimserver traceLevel=4 traceComponents=ALL (starts server with config flags)

bin/cimprovider �l �s (lists providers and their status)

bin/cimprovider �e �m OperatingSystemModule (enables the OperatingSystem provider)

bin/cimuser �a �u guest �w ThePassword

bin/cimuser �l (lists the users)

bin/tomof CIM_Config (extract CIM_Config from repository and present it in MOF type)

16. Creating SSL certifications

================================

Please follow section 11, titled "Notes about Building Pegasus with SSL"

before embarking on this endeavour.

Type these commands in your shell to create the SSL certifications. The PEGASUS_ROOT

and PEGASUS_HOME have to be set to your respective installation and source directory.

CN="Common Name"

EMAIL="test@email.address"

HOSTNAME=`uname -n`

sed -e "s/$CN/$HOSTNAME/" \

-e "s/$EMAIL/root@$HOSTNAME/" $PEGASUS_ROOT/src/Server/ssl.cnf \

> $PEGASUS_HOME/ssl.cnf

chmod 644 $PEGASUS_HOME/ssl.cnf

chown bin $PEGASUS_HOME/ssl.cnf

chgrp bin $PEGASUS_HOME/ssl.cnf

/usr/bin/openssl req -x509 -days 365 -newkey rsa:512 \

-nodes -config $PEGASUS_HOME/ssl.cnf \

-keyout $PEGASUS_HOME/key.pem -out $PEGASUS_HOME/cert.pem

cat $PEGASUS_HOME/key.pem $PEGASUS_HOME/cert.pem > $PEGASUS_HOME/server.pem

cp $PEGASUS_HOME/cert.pem $PEGASUS_HOME/client.pem

rm $PEGASUS_HOME/key.pem $PEGASUS_HOME/cert.pem

17. Configuring Pegasus to use SSL

================================

Please follow section 11 and 16 before reading this section.

To configure Pegasus to take advantage of SSL, configure

cimserver_planned.conf to have:

sslTrustFilePath=client.pem

sslCertificateFilePath=server.pem

sslKeyFilePath=file.pem

httpsPort=5989

enableHttpsConnection=true

(The client.pem and server.pem are the certifications

files created per the steps in the earlier section).

For good riddance you might consider closing down

the cleartext 5988 port. Modify your cimserver_planned.conf

to include:

enableHttpConnection=false

18. Testing with ICU enabled:

==============================

ICU (International Compoments for Unicode) refers to the set of libraries that

Pegasus uses to run globalized. For example: these libraries are used to

load messages in different languages, format currency and numbers according to

a specific locale etc. In order to enable globalization in Pegasus, Pegasus

must be built with ICU enabled, ie. the right environment variables must be

set prior to running "make". Refer to the GlobalizationHOWTO.htm in the docs

directory for details. That said, when users run "make poststarttests"

to verify the integrity of a Pegasus download, a series of tests are run that

require the cimserver to be running. These tests currently depend on specific

messages returned from the server. When ICU is enabled, all messages come

from the resource bundles and these usually do not match the hardcoded

default messages within Pegasus. These hardcoded default messages

are what the various test programs expect in order to complete

successfully. If the ICU enabled server is started without

disabling message loading from the bundles, "make poststartests" will fail.

In order to run "make poststarttests" successfully with ICU enabled, an

environment variable called PEGASUS_USE_DEFAULT_MESSAGES must exist prior to

starting the server. Once this is defined, when the cimserver starts, all

messages generated will be the default hardcoded messages. This will enable

"make poststarttests" to complete successfully. Once "make poststarttests" is

complete, you should stop the cimserver and then undefine PEGASUS_USE_DEFAULT_MESSAGES.

If this variable is left defined, Pegasus will not be able to load messages

using ICU resource bundles.

19. Documentation:

===================

The documentation is currently in preperation. The preliminary documentation

is not provided with this snapshot but is avialable from the OpenGroup Pegasus

Line 381

Line 621

documentation in the future and today is the source of most discussion and

design documentation.

Participate!

============

20. Participate!

=================

We are looking for people who want to join the Pegasus work group and

contribute to effort of getting this Pegasus off the ground. Please send

contribute to effort of getting this Pegasus off the ground. Please join

email for details to k.schopmeyer@opengroup.org or m.kirk@opengroup.org or

the mailing list by visiting www.openpegasus.org, and click on Mailing Lists.

m.brasher@opengroup.org

Legend:

Removed from v.1.10
changed lines
	Added in v.1.16.2.1

No CVS admin address has been configured