1 karl 1.1 Pegasus - A Manageability Services Broker for the DMTF CIM/WBEM Standards
2
|
3 mike 1.3 Author: Mike Brasher, Karl Schopmeyer
4
|
5 karl 1.6 Version 0.97
6 May 20 2001
7
|
8 karl 1.4 ------------------------------------------------------------------------------
9 --
10
11 $Log: readme.txt,v $
|
12 karl 1.6 Revision 1.5 2001/02/26 10:36:34 karl
13 Clean Up Text
14
|
15 karl 1.5 Revision 1.4 2001/01/26 20:20:36 karl
16 Clean up Readme with MB comments
17
|
18 karl 1.4 Revision 1.3 2001/01/22 15:09:29 mike
19 Reworking indentation and breaking width of lines below 80 columns (not
20 finished). Also
21 inserted comments and suggestions following "MEB:" annotations.
|
22 karl 1.1
23
|
24 karl 1.2 Revision 1.1 2001/01/15 04:26:04 karl
25 added Readme
26
|
27 karl 1.6 -----------------------------------------------------------------------
|
28 karl 1.1
29 Tagline: Pegasus is an object manager for DMTF CIM objects written in C++
|
30 karl 1.5 and supported by The Open Group
|
31 karl 1.4
|
32 karl 1.5 Pegasus is an open-source object manager for DMTF CIM objects. It is written
33 in C++ and includes the Object manager, a set of defined interfaces, and SDKs
34 for both client, providers, and services extensions. It is maintained
35 consistent with the DMTF CIM and WBEM specifications except for any exceptions
36 noted in the documentation.
|
37 karl 1.1
38 This distribution represents a work in progress towards building a Pegasus
|
39 mike 1.3 release. Pegasus is open source and is covered under the following license.
|
40 karl 1.1 This version is incomplete and is directed towards evaluators and developers
41 of the Pegasus Architecture.
42
43 Pegasus is being developed and maintained under the auspices of The Open
44 Group. Pegasus is maintained under the license defined in the doc directory
45 (LICENSE) of this release. This licensing is intended to support as wide a
46 distribution as possible with minimal demands on the users.
47
48 This distribution represnts a snapshot of the current work. Currently Pegasus
49 is in phase 1 of a multiphase development project. This snapshot is primarily
50 for developers and for evaluation of the project.
51
|
52 mike 1.3 More information on this project, access to the CVS, and documentation on
53 Pegasus are available from the OpenGroup WEB site.
|
54 karl 1.1
55 There are separate files in the release for
56
57 History of releases - HISTORY
58 What's new for this release - WHATSNEW
59 What's Broken - BUGS
60
61 In addition, the roadmap for Pegasus and further information on the project is
62 available on The Opengroup Pegasus WEB Site.
63
64 http://www.opengroup.org/MSB
65
66 Availability of Pegasus
67 =======================
68
69 Pegasus is distributed as open source. Today the distribution is limited
70 because we want to reach a predefined level of development before making the
71 project publically available. The move from limited to open distribution will
72 be a decision of the Pegasus development team and The Open Group and should
73 occur before March 2001.
74
75 karl 1.1 To get on the distribution list for Pegasus today, send an email to
76
|
77 karl 1.6 m.kirk@opengroup.org
|
78 mike 1.3
|
79 karl 1.6 or
|
80 mike 1.3
|
81 karl 1.6 k.schopmeyer@opengroup.org
|
82 karl 1.1
83 Pegasus Major Components
84 ========================
|
85 mike 1.3
|
86 karl 1.1 The major components of Pegasus are:
87
|
88 mike 1.3 Pegasus Server - WBEM/CIM Server with interfaces for providers and clients
|
89 karl 1.1
|
90 karl 1.5 Pegasus Repositories - Today Pegasus provides a defined class repository
91 interface and a simple file based class repository. It also includes
92 an instance repository. Note that these repository were created for
93 functionality, not efficieny. It is expected that they will be replaced
94 with other implementations of the respository function as the need arrses.
|
95 mike 1.3
|
96 karl 1.4 Pegasus Client SDK - Tools for building Pegasus clients based on the Pegasus
97 C++ interfaces and using the WBEM HTTP/XML protocols or directly
|
98 mike 1.3 interfacing with Pegasus.
99
|
100 karl 1.4 Pegasus Test Clients - Simple test clients being developed as part of the
|
101 mike 1.3 Pegasus development process
102
|
103 karl 1.4 Pegasus HTML Test Client - To aid in testing we created a test client for
104 Pegasus that uses a WEB server (ex. Apache) with a set of CGI modules and
105 HTML to allow the entry of Pegasus operations from a WEB browser as forms
106 and the recept of the response as WEB pages. This has proven useful as a
|
107 mike 1.3 test tool and can be used for a wide variety of demonstrations.
|
108 karl 1.1
|
109 karl 1.5 Pegasus Provider SDK - Tools for build Pegasus clients based on the Pegasus
110 C++ interfaces.
111
112 Pegasus Providers - A sampling of key providers to make the environment
113 complete as well as test providers and demonstration providers for the
114 Pegasus.
|
115 karl 1.1
116 Pegasus Service Extensions - Future (version 1.0)
117
|
118 karl 1.5 Pegasus MOF Compiler - FA standalone compiler for MOF files that can be used
119 to install MOF into the Pegasus schema repository and also to check syntax
|
120 karl 1.1
121 Pegasus Dependencies
|
122 mike 1.3 ====================
|
123 karl 1.1
124 We have worked to minimize the dependence of Pegasus on other software
125 packages and tools. Currently Pegasus has the following dependencies
126
|
127 karl 1.6 1. To simplify the building of Pegasus across multiple platforms we have
|
128 mike 1.3 standardized on a set of build tools including: GNUMAKE. We are using GNUAKE
|
129 karl 1.1 4.79.1 successfully both in Windows and Linux environments.
130
131 GNUMAKE is available from
132
133 http://www.gnu.org
134
135 ATTN: I think we need to make our version available on the TOG site.
136
|
137 karl 1.4 COMMENT: Unless other users of Pegasus demand it, we will NOT create any build
138 environment for Pegasus that does not require GNUMAKE (e.g., Visual C++). We
139 are open to other developers who want to contribute other build structures for
|
140 mike 1.3 particular environments.
|
141 karl 1.1
142
|
143 karl 1.6 2. MU.EXE - To minimize the difference between Linux and Windows for GUNMAKE,
|
144 karl 1.4 we have created a utility called MU.exe. This utility is required for Pegasus
145 make with Windows environment. It is provided as an alternative to requiring a
146 number of UNIX utilities (SH, RM, etc.) on the windows platform and
147 effectively provides the functions of these utilities that GNUMAKE needs.
|
148 karl 1.5 MU is not required on UNIX or LINUX platforms.
|
149 karl 1.4
150 NOTE: The binary for MU.EXE is not distributed in the Pegasus bin directory.
151 You must build it separately. MU source code is part of the distribution
152 in the directory src/utils/MU with its own make file. You must compile MU
153 before you initiate the Pegausu make.
|
154 mike 1.3
|
155 karl 1.4 NOTE: We will make a copy of the binary available on the MSB WEB site to
156 eliminate the requirement to build this utility.
|
157 mike 1.3
|
158 karl 1.6 3. FLEX and BISON - These tools were used to develop the compiler, anybody
|
159 karl 1.5 intending to recompile the compiler from scratch will be required to have
160 these tools.
161
|
162 karl 1.6 4. DOC++ - The Pegasus documentation is taken from a combination of text files
|
163 karl 1.5 and the Pegasus header files themselves. This documentation is formatted with
164 DOC++ and GAWK. These tools are required if the documentation is to be
165 recreated but we expect that only the core team will be recreating
166 documentaiton.
167
|
168 karl 1.6 5. ACE_Wrappers communication package (NOTE: The ACE Wrappers dependency has
169 been removed. Effective version 0.9 Pegasus is not dependent on ACE Wrappers)
170 - The ACE Wrappers package is used for
171 communication and some low level functions within the MSB, the Pegasus client
172 SDK, and the Pegasus Provider SDK. ACE is available from the following site.
173
174 http://ace.cs.wustl.edu/cvsweb/ace-cvs.cgi/ACE_wrappers/
175
176 Currently we are using version 5.1 of ACE_Wrappers both in Linux and Windows.
177
178 http://www.cs.wustl.edu/~schmidt/ACE_wrappers/ACE-5.1.tar.gz
179
180 COMMENTS: Pegasus only uses limited facilities from ACE. We actively
181 discourage the Pegasus team from using other functions of ACE. We expect to
182 eliminate our dependence on ACE as the only TCP tool in the near future.
183 However, today Pegasus demands the installation of the complete ACE library.
184 One of the action items for the future is to provide a more limited ACE
185 library and possibly even to provide an environment independent of ACE.
|
186 mike 1.3
|
187 karl 1.1 The Pegasus Directory Structure
188 ===============================
189
|
190 karl 1.4 Pegasus is distributed as a complete directory structure that should be
|
191 mike 1.3 installed either from one of the snapshots or from CVS.
|
192 karl 1.1
193 This structure is generally as follows
|
194 mike 1.3
|
195 karl 1.4 Pegasus Pegasus Root directory
|
196 karl 1.5
197
198 build Default destination for runtime if PEGASUS_HOME
199 is not specified. Does not exist if PEGASUS_HOME
200 is specified
201
202
203 cgi Source for the Pegasus WEB Based Test client
204 cgi-bin CGI Directories for WEB demonstration.
205 This directory is normally empty but can
206 be populated from the runtime with the make
207 from cgi.
208 htdocs HTML Pages for Pegasus WEB emonstration
209 doc Miscellaneous Pegasus Documents.
|
210 karl 1.4 DevManual Source and build files for developes manual
211 mak General make files (used by other makes)
|
212 karl 1.1 src All Pegasus Source Files
|
213 karl 1.4 ACEExample Test directrory with examples of the use of ACE
214 Clients Source for various test clients and client SDK
215 CGICLIENT Pegasus test client that uses a WEB browser
|
216 karl 1.1 Pegasus
|
217 karl 1.4 Client Pegasus Client API Tests
|
218 karl 1.1 depends
219 tests
220 Common Pegasus Common Functions (C++ source and headers
221 tests Test programs for the common functions
222 Protocol Pegasus Client HTTP/XML Protocol Modules
223 depends
|
224 karl 1.4 Provider Pegasus Provider interface functions
225 Repository Pegasus Repository Interfaces and Simple
|
226 karl 1.5 Repository
|
227 karl 1.1 tests Tests for Repository Functions
228 Server Pegasus Server Modules
|
229 karl 1.5 Providers Pegasus test and required providers
230
|
231 karl 1.1 Utils
|
232 karl 1.5
233 Runtime Directories
234 $PEGASUS_HOME$ Home directory for runtime. All compiler, linker
235 documentation creation, etc. is put here.
236 bin Destination for executable and DLL modules from
237 Pegasus build
238 Manual HTML output of the Pegasus Manual
239 lib Destination for Pegasus LIB modules
240 obj Destination for object modules
241 Repository This Directory containes the created repository
242
|
243 karl 1.1
244 In the near future we will add directories for:
245
246 Service Extensions
|
247 karl 1.5 Servers - Today the server executable is built from /server/test.
|
248 karl 1.1
249 Installation
250 ============
251
|
252 karl 1.4 Pegasus today is provided only as a source distribution. You download compile
253 and use it. Pegasus currently compiles and runs under both Linux and Windows
254 NT environments.
255
256 The installation of Pegasus involves expanding the snapshot distribution
257 files, building the runtime, the test files and test clients, and building the
258 repository.
259
|
260 karl 1.1 Building from a Distribution --- General
261 ========================================
262
263 Pegasus is buildable and runnable on either Linux or WIndows Platforms today.
|
264 karl 1.5 It uses a common build system for the two platforms based on build files in
265 each directory, a recursive build strucutre to execute the multiple makes and
|
266 karl 1.1 GUNMAKE.
267
|
268 karl 1.5 Generally we support the followingtargets in our make system:
|
269 karl 1.1
270
|
271 karl 1.5 C:\> make clean - Clean out all objects, libs, and executables
272 C:\> make depend - Create the dependencies
|
273 karl 1.1 C:\> make
|
274 karl 1.5 C:\> make tests - Execute all tests except client server tests
275 C:\> make rebuild - Clean and rebuild including the respository
276 C:\> make world
|
277 karl 1.1
|
278 karl 1.4 The Pegasus Client server tests are executed separately from the above because
279 they require the initiation of separate process for the Pegasus server and
280 Pegasus client. These tests can be executed as follows:
|
281 karl 1.1
282 ATTN: Add the procedure for Client/Server Test start here.
283
284
|
285 karl 1.4 For information on particular installation characteristics, tools, etc. for
|
286 karl 1.6 each platform see the appropriate sections below:
|
287 karl 1.1
288 Generally the build commands are as follows:
289
|
290 karl 1.6 1. There is a Makefile in the Pegasus root directory. Simply executing
291 make in the Pegasus root directory will make everything. "Make rebuild"
292 will clean and rebuild everything. The "make rebuild" will also populate
293 the repository with the current CIM Schemas.
|
294 karl 1.1
|
295 karl 1.6 2. To test a fresh release, go to the pegasus root and type
|
296 karl 1.1
297 "make world".
298
299
|
300 karl 1.6 This will build dependencies, build binaries, and then run all
|
301 karl 1.4 tests except the Client/Server tests.
|
302 karl 1.1
|
303 karl 1.6 3. To execute the basic test suite that is shipped with pegasus type
|
304 karl 1.1
|
305 karl 1.6 "make tests". This also reintalls the repository.
|
306 karl 1.1
|
307 karl 1.4 Running "make -s tests" suppresses extraneous output such as the
308 enter/leave directory messages.
|
309 karl 1.1
|
310 karl 1.6 4. "Make Clean" removes all object and library files from the structure.
|
311 karl 1.1
312 Build Variables
313 ===============
314
|
315 karl 1.5 The build system depends on the following environment variables build set.
316 These variables must be set as part of the installation of the Pegasus source
317 tree before you can compile or run Pegasus.
|
318 karl 1.1
|
319 karl 1.4 PEGASUS_OS_TYPE - optional. The is currently set to windows. If you build
|
320 karl 1.5 on any platform except windows you must change this before initiating
321 make.
|
322 karl 1.1
|
323 karl 1.6 PEGASUS_ROOT - Root directory of the Pegasus source tree.
324
|
325 karl 1.5 PEGASUS_HOME - Home directory for all of the Pegasus runtime elements.
326 If this does not exist, $PEGASUS_ROOT$/build is assumed.
|
327 karl 1.4
328 COMMENTS: In the future, we will probably automate this more. However,
329 setting these variables today is manual.
|
330 karl 1.1
331
332 The MU Utility
333 ==============
334
|
335 karl 1.4 In order to provide a consistent build structure across multiple platforms, we
336 developed a small utility to provide a consistent set of small utilities
337 across these platforms. The MU utilityis a simple utility that contains many
338 commands. For example:
|
339 karl 1.1
340
341 C:\> mu rm myfile.cpp yourfile.cpp
342
343
344 You may type "mu" to get a list of valid commands. Here are some
345 of them:
346
347
|
348 karl 1.2 rm, rmdirhier, mkdirhier, echo, touch, pwd, copy, move, compare depend
|
349 karl 1.1
350
351 The MU utility supports globing (expansion of wildcards) so
352 you can do things like this:
353
354
355 C:\> mu rm *.obj *.exe
356
|
357 karl 1.4 MU is required to build under the Windows environment.MU is available as part
358 of the distribution of Pegasus.
|
359 karl 1.1
360 Building Pegausu on Linux
361 =========================
362
|
363 karl 1.5 1. Obtain, unpack and build the ACE_Wrappers package for Linux.
364
365 2. Define an environment variable called ACE_ROOT that points to the
366 root of the ACE_WRAPPERS distribution. For example
|
367 karl 1.1
|
368 karl 1.5 IMPORT PEGASUS_ACE_ROOT=\local\ACE_Wrappers
|
369 karl 1.1
|
370 karl 1.5 ATTN: Mike. what is a viable directory for Linux (what do you use)
|
371 karl 1.1
|
372 karl 1.5 3. Define an environment variable PEGASUS_ROOT that points to the
373 root of the Pegasus Distribution
|
374 karl 1.1
375
|
376 karl 1.5 4. Define the environment variable PEGASUS_HOME where you want the
377 runtime elements (executables, objects, libraries, etc.) to go.
378 5. Unpack the ace distribution.
|
379 karl 1.1
380
|
381 karl 1.5 6. Append %PEGASUS_ROOT%/bin to your path
|
382 karl 1.1
|
383 karl 1.5 7. From the %PEGASUS_ROOT% directory build using the make commands
384 defined in the section on General Build.
|
385 karl 1.1
|
386 karl 1.5 make world
387 make tests
|
388 karl 1.1
|
389 karl 1.5 Building Pegasus on NT or Windows 2000 With Microsoft Visual C++
390 ================================================================
|
391 karl 1.1
392 Today we build Pegasus on Windows NT using a set of make files contained
393 in the source distribution, the Microsoft compilers (tested so far with
394 versions 5 and 6) and the GNUMAKE make utility. The following is the basic
395 set up steps for the
396
397
|
398 karl 1.4 1. Setup the environment variables and path for the Micrososft Visual C
|
399 karl 1.5 compiler. Typically this can be done by running the VCVARS32.BAT file
400 supplied with Microsoft Visual C++. (contained in the same directory
401 as cl.exe).
|
402 karl 1.1
403 2. Define an environment variable called ACE_ROOT that points to the
|
404 karl 1.5 root of the ACE_Wrappers distribution. For example:
|
405 karl 1.1
|
406 karl 1.5 C:\> set PEGASUS_ACE_ROOT=c:/ACE_wrappers
|
407 karl 1.1
|
408 karl 1.5 Now append %ACE_ROOT%/bin to the path like this:
|
409 karl 1.1
|
410 karl 1.5 C:\> set path=%path%;%PEGASUS_ACE_ROOT%/bin
|
411 karl 1.1
412 3. Define an environment variable called PEGASUS_ROOT that points to
|
413 karl 1.5 the root of the Pegasus distribution. For example:
|
414 karl 1.1
|
415 karl 1.5 C:\> set PEGASUS_ROOT=c:/pegasus
|
416 karl 1.1
417
|
418 karl 1.5 4. Setup the PEGASUS_HOME environment variable
419 set PEGASUS_HOME=c:/PegasusRun
|
420 karl 1.1
|
421 karl 1.5 Now append %PEGASUS_HOME%/bin to your path like this:
|
422 karl 1.1
|
423 karl 1.5 set path=%path%;%PEGASUS_HOME%/bin
|
424 karl 1.1
|
425 karl 1.5 5. Unpack and build the ACE_Wrappers distribution for windows.
|
426 karl 1.1
|
427 karl 1.5 As an example, we created a file called %ACE_ROOT%/ace/config.h
428 containing the following:
|
429 karl 1.1
|
430 karl 1.5 #include "ace/config-win32.h"
|
431 karl 1.1
|
432 karl 1.5 and then opened this DSW file in MSVC++ IDE:
|
433 karl 1.1
|
434 karl 1.5 %ACE_ROOT%/ace/ace.dsw
|
435 karl 1.1
|
436 karl 1.5 From the build menu we picked "ace.dll". For me it built without
437 complaint.
|
438 karl 1.1
|
439 karl 1.5 The ACE package can be built in several configurations:
|
440 karl 1.1
|
441 karl 1.5 ace.dll - The basic package without debugging
442 aced.dll - debugging added to the basic package
443 acemfc.dll - ACE with Microsoft MFC support
444 acemfcd.dll - The ACE MFC version with debugging.
|
445 karl 1.1
|
446 karl 1.5 ace.dll is used for the server build acemfc is used for the client
447 builds.
|
448 karl 1.1
|
449 karl 1.5 NOTE: In the near future we will be building debugging options into
450 Pegasus and at that time the aced and acemfcd libraries will also be
451 required.
|
452 karl 1.1
|
453 karl 1.5 Each library can be built separately from Microsoft Visual C++.
|
454 karl 1.1
|
455 karl 1.5 6. Unpack the Pegasus distribution. On Windows systems, PKzip25 or
456 WINZIP can be used. Be certain to use the option that expands the
457 directory tree of the files. This expansion will create a directory
458 called ./pegasus
|
459 karl 1.1
|
460 karl 1.5 If you are using pkzip25.exe do this:
461 C:\> pkzip25 -extract -recurse -directories pegasus.zip
|
462 karl 1.1
|
463 karl 1.5 This will create a directory tree called ./pegasus under the
464 current directory.
|
465 karl 1.1
466
|
467 karl 1.5 7. Change directory to %PEGASUS_ROOT% and type "make world". See the
468 general build section for the full set of make commands.
|
469 karl 1.1
|
470 karl 1.5 This builds Pegasus and all of its examples.
471
472 7. To verify that it built okay, run the tests
473
474 make tests
|
475 karl 1.1
476 Installing the Pegasus HTML Test Client
477 =======================================
478
|
479 karl 1.4 This is a separate test tool that allows Pegasus requests to be initiated from
480 any WEB browser and that uses a WEB browser, CGI scritps and HTML pages for
481 the formating and connections. It requires a WEB server, etc. The
482 instructions for setting up this environment are maintained in a separate
483 readme in the CGI directory.
|
484 karl 1.1
485 Development with Pegasus and Pegasus Tools
486 ==========================================
487
488 ATTN: This section needs to be completed. It should reference the more
489 complete documentation
490
491 ===================
492 Documentation
493
|
494 karl 1.4 The documentation is currently in preperation. The preliminary documentation
495 is not provided with this snapshot but is avialable from the OpenGroup Pegasus
496 WEB pages. The current documentation is maintained both as a manual created
|
497 karl 1.5 under the tool DOC++ in the runtime subdirectory manual/html and as other
498 miscelaneous documentation in the doc directory.
|
499 karl 1.4
500 Note that the Pegasus WEB site at The Open Group will be the source of most
501 documentation in the future and today is the source of most discussion and
502 design documentation.
|
503 karl 1.1
504 Participate!
505 ============
|
506 karl 1.4 We are looking for people who want to join the Pegasus work group and
507 contribute to effort of getting this Pegasus off the ground. Please send
508 email for details to k.schopmeyer@opengroup.org or m.kirk@opengroup.org or
509 m.brasher@opengroup.org
|
510 karl 1.6
|
511 karl 1.5
512
|
513 karl 1.4
514
515
|
516 karl 1.1
517
518
519
520
521
522
523
524
525
526
527
|