1 karl 1.11
2 OpenPegasus - A Manageability Services Broker for the DMTF CIM/WBEM Standards
|
3 karl 1.1
|
4 mike 1.3 Author: Mike Brasher, Karl Schopmeyer
5
|
6 karl 1.11 Tagline: OpenPegasus is an object manager for DMTF CIM objects written in C++
|
7 karl 1.5 and supported by The Open Group
|
8 karl 1.4
|
9 karl 1.11 STATUS: Revised June 2003 to match Pegasus release 2.2
10 Contents:
|
11 mike 1.7 =========
12
|
13 karl 1.11 1. Overview
14 2. Availability of Pegasus
15 3. Pegasus major components
16 4. Pegasus Dependencies
17 5. The Pegasus Directory Structure
18 6. Installation
19 7. Building Pegasus
20 8. Populate the Repository
21 9. The MU Utility
22 10. Notes about Building Pegasus on Linux
23 11. Notes on building Pegasus with SSL
24 12. Building Pegasus on Windows 2000 or Windows XP With Microsoft Visual C++
25 13. Installing the Pegasus HTML Test Client
26 14. Development with Pegasus and Pegasus Tools
27 15. Commands
28 16. Creating SSL certifications.
29 17. Documentation
30 18. Participate
31
32
33
34 karl 1.11
35 1. Overview:
36 ============
37
38 OpenPegasus (also refered to as Pegasus):
39
|
40 karl 1.5 Pegasus is an open-source object manager for DMTF CIM objects. It is written
41 in C++ and includes the Object manager, a set of defined interfaces, and SDKs
42 for both client, providers, and services extensions. It is maintained
43 consistent with the DMTF CIM and WBEM specifications except for any exceptions
44 noted in the documentation.
|
45 karl 1.1
46 This distribution represents a work in progress towards building a Pegasus
|
47 mike 1.3 release. Pegasus is open source and is covered under the following license.
|
48 karl 1.1 This version is incomplete and is directed towards evaluators and developers
49 of the Pegasus Architecture.
50
51 Pegasus is being developed and maintained under the auspices of The Open
52 Group. Pegasus is maintained under the license defined in the doc directory
53 (LICENSE) of this release. This licensing is intended to support as wide a
54 distribution as possible with minimal demands on the users.
55
|
56 karl 1.11 This distribution represents a snapshot of the current work. Currently Pegasus
|
57 karl 1.1 is in phase 1 of a multiphase development project. This snapshot is primarily
58 for developers and for evaluation of the project.
59
|
60 mike 1.3 More information on this project, access to the CVS, and documentation on
61 Pegasus are available from the OpenGroup WEB site.
|
62 karl 1.1
63 There are separate files in the release for
64
|
65 karl 1.11 History of releases - HISTORY
66 What's new for this release - WHATSNEW
67 What's Broken - BUGS
|
68 karl 1.1
69 In addition, the roadmap for Pegasus and further information on the project is
70 available on The Opengroup Pegasus WEB Site.
71
|
72 karl 1.11 http://www.openpegasus.org
73
74
75 2. Availability of Pegasus:
76 ============================
77
78 Pegasus is distributed as open source. The distribution is available via
79 CVS and snapshot images in tar and zip file formats.
80
81 The source code from CVS can be found at the following Open Group CVS server;
82
83 cvs.opengroup.org:/cvs/MSB
84
85 using the password authenticating server option (pserve).
86
87 Anonymous access for read is with the name and password "anon" as follows:
88
89 %export CVSROOT=:pserver:anon@cvs.opengroup.org:/cvs/MSB
90 %cvs login
91
92 When requested, enter the password "anon"
|
93 karl 1.1
|
94 karl 1.11 The source tree is in the directory pegasus. To check out the complete Pegasus
95 source tree just type:
|
96 karl 1.1
|
97 karl 1.11 cvs co pegasus
|
98 karl 1.1
|
99 karl 1.11 A Pegasus directory will be created under the current directory and populated
100 with the complete source tree and documentation. To get the latest updates
101 after a checkout just type this from Pegasus root:
|
102 karl 1.1
|
103 karl 1.11 cvs update -d
|
104 mike 1.3
105
|
106 karl 1.11 Active contributors to Pegasus have write access to the CVS repository.
107 If you are interested in contributing back to the Pegasus project,
108 (i.e. write (checkin) access to CVS) please request access from either
109 Martin Kirk (m.kirk@opengroup.org) or Karl Schopmeyer (k.schopmeyer@opengroup.org).
|
110 karl 1.1
|
111 karl 1.11
112 3. Pegasus Major Components:
113 =============================
|
114 mike 1.3
|
115 karl 1.1 The major components of Pegasus are:
116
|
117 mike 1.3 Pegasus Server - WBEM/CIM Server with interfaces for providers and clients
|
118 karl 1.1
|
119 karl 1.5 Pegasus Repositories - Today Pegasus provides a defined class repository
120 interface and a simple file based class repository. It also includes
121 an instance repository. Note that these repository were created for
122 functionality, not efficieny. It is expected that they will be replaced
|
123 karl 1.11 with other implementations of the respository function as the need arises.
|
124 mike 1.3
|
125 karl 1.4 Pegasus Client SDK - Tools for building Pegasus clients based on the Pegasus
126 C++ interfaces and using the WBEM HTTP/XML protocols or directly
|
127 mike 1.3 interfacing with Pegasus.
128
|
129 karl 1.4 Pegasus Test Clients - Simple test clients being developed as part of the
|
130 mike 1.3 Pegasus development process
131
|
132 karl 1.4 Pegasus HTML Test Client - To aid in testing we created a test client for
133 Pegasus that uses a WEB server (ex. Apache) with a set of CGI modules and
134 HTML to allow the entry of Pegasus operations from a WEB browser as forms
|
135 karl 1.11 and the receipt of the response as WEB pages. This has proven useful as a
|
136 mike 1.3 test tool and can be used for a wide variety of demonstrations.
|
137 karl 1.1
|
138 karl 1.11 Pegasus Provider SDK - Tools for building Pegasus providers using the Pegasus
|
139 karl 1.5 C++ interfaces.
140
|
141 karl 1.11 Pegasus Providers - Providers to illustrate the use of Pegasus services including
142 providers for test and demonstration.
|
143 karl 1.1
|
144 karl 1.11 Pegasus Service Extensions - Common services for use by other Pegasus
145 components to extend Pegasus capabilites.
|
146 karl 1.1
|
147 karl 1.5 Pegasus MOF Compiler - FA standalone compiler for MOF files that can be used
|
148 karl 1.11 to install MOF into the Pegasus schema repository and also to check syntax.
149 There is also a tool to extract the MOF from the repository.
|
150 karl 1.1
|
151 karl 1.11
152 4. Pegasus Dependencies:
153 =========================
|
154 karl 1.1
155 We have worked to minimize the dependence of Pegasus on other software
|
156 karl 1.11 packages and tools. Currently Pegasus has the following dependencies:
|
157 karl 1.1
|
158 mike 1.7 1. GNUMAKE - To simplify the building of Pegasus across multiple platforms we
159 have standardized on a set of build tools including: GNUMAKE. We are using
|
160 kumpf 1.12 GNUMAKE 3.79.1 successfully both in Windows and Linux environments.
|
161 karl 1.1
|
162 mike 1.7 GNUMAKE is available from
|
163 karl 1.1
164 http://www.gnu.org
165
|
166 mike 1.7
|
167 karl 1.11 2. MU.EXE - To minimize the difference between Linux and Windows for GNUMAKE,
|
168 mike 1.7 we have created a utility called MU.exe. This utility is required for
|
169 karl 1.11 Pegasus make with ONLY Windows environment. It is provided as an alternative to
|
170 mike 1.7 requiring a number of UNIX utilities (SH, RM, etc.) on the windows platform
171 and effectively provides the functions of these utilities that GNUMAKE
172 needs. MU is not required on UNIX or LINUX platforms.
173
174 NOTE: The binary for MU.EXE is not distributed in the Pegasus bin directory.
175 You must build it separately. MU source code is part of the distribution
176 in the directory src/utils/MU with its own make file. You must compile MU
177 before you initiate the Pegausu make.
178
|
179 karl 1.11 NOTE: A copy of the binary is made available as a zip file on the Pegasus
180 WEB site.
181
182 Again, MU is used ONLY if you are using Windows.
183
|
184 mike 1.7
|
185 karl 1.11 3. FLEX and BISON - These tools were used to develop the MOF compiler and WQL
186 parser. Anybody intending to recompile the compiler or parser from scratch
187 will be required to have these tools. They are only required if changes need
188 to be made to the files for parsing and compiling.
|
189 mike 1.7
190 4. DOC++ - The Pegasus documentation is taken from a combination of text files
191 and the Pegasus header files themselves. This documentation is formatted
192 with DOC++ and GAWK. These tools are required if the documentation is to
193 be recreated but we expect that only the core team will be recreating
194 documentaiton.
|
195 mike 1.3
|
196 karl 1.11
197 5. The Pegasus Directory Structure
198 ===================================
|
199 karl 1.1
|
200 karl 1.4 Pegasus is distributed as a complete directory structure that should be
|
201 mike 1.3 installed either from one of the snapshots or from CVS.
|
202 karl 1.1
203 This structure is generally as follows
|
204 mike 1.3
|
205 karl 1.4 Pegasus Pegasus Root directory
|
206 karl 1.5
207 cgi Source for the Pegasus WEB Based Test client
|
208 karl 1.11 cgi-bin CGI Directories for WEB demonstration.
209 This directory is normally empty but can
210 be populated from the runtime with the make
211 from cgi.
212 htdocs HTML Pages for Pegasus WEB emonstration
|
213 karl 1.5 doc Miscellaneous Pegasus Documents.
|
214 karl 1.11 DevManual Source and build files for developers' manual
|
215 karl 1.4 mak General make files (used by other makes)
|
216 karl 1.1 src All Pegasus Source Files
|
217 karl 1.11 ACEExample Test directrory with examples of the use of ACE
218 Clients Source for various test clients and client SDK
|
219 karl 1.4 CGICLIENT Pegasus test client that uses a WEB browser
|
220 karl 1.1 Pegasus
|
221 karl 1.4 Client Pegasus Client API Tests
|
222 karl 1.1 depends
223 tests
224 Common Pegasus Common Functions (C++ source and headers
225 tests Test programs for the common functions
226 Protocol Pegasus Client HTTP/XML Protocol Modules
227 depends
|
228 karl 1.11 Provider Pegasus Provider interface functions
229 Repository Pegasus Repository Interfaces and Simple Repository
|
230 karl 1.1 tests Tests for Repository Functions
231 Server Pegasus Server Modules
|
232 karl 1.11 Providers Pegasus test and required providers
|
233 karl 1.5
|
234 karl 1.1 Utils
|
235 karl 1.5
236 Runtime Directories
|
237 karl 1.11 $PEGASUS_HOME$ Home directory for runtime. All compiler, linker
|
238 karl 1.5 documentation creation, etc. is put here.
|
239 karl 1.11 bin Destination for executable and DLL modules from
240 Pegasus build
241 Manual HTML output of the Pegasus Manual
242 lib Destination for Pegasus LIB modules
243 obj Destination for object modules
244 repository This Directory contains the created repository
|
245 karl 1.5
|
246 karl 1.1
|
247 karl 1.11 6. Installation
248 ================
|
249 karl 1.1
|
250 karl 1.11 Pegasus today is provided only as a source distribution.
|
251 karl 1.1
|
252 karl 1.11 To install Pegasus, you must check it out using CVS (Common Version System)
253 or download the snapshot. You download, compile, and use it.
254
255 For the snapshot, the installation of Pegasus involves expanding the snapshot
256 distribution files, building the runtime, the test files and test clients, and
257 building the repository.
|
258 karl 1.1
|
259 karl 1.4
|
260 karl 1.11 7. Building Pegasus
261 =====================
|
262 mike 1.7
263 1. Check that you have requisite programs (listed in Pegasus Dependencies).
264
|
265 karl 1.11 These include GNU Make, MU.EXE (if using Windows), Flex, and Bison (Flex
266 and Bison only required if changes will be made to the MOF compiler or WQL
267 parser).
|
268 mike 1.7
269 Be sure these are on your path.
270
|
271 karl 1.11
272 2. Define the following three environment variables:
273
274 PEGASUS_ROOT - this should be the "pegasus" directory you've pulled from CVS
|
275 mike 1.7
276 PEGASUS_HOME - to point to a directory to contain output binary files
|
277 karl 1.11 (e.g., set it to $HOME/pegasus_home). Then the output will go into
278 $HOME/pegasus_home/bin and $HOME/pegasus_home/lib
|
279 mike 1.7
280 PEGASUS_PLATFORM - this must be set to a supported platform identifier.
281
|
282 karl 1.11 This identifier has the following form:
283
284 <Operating-System>_<Architecture>_<Compiler>
|
285 mike 1.7
|
286 karl 1.11 For example (Linux on IA32 platform using the GNU Compiler):
287 LINUX_IX86_GNU
288
289 For a complete list, refer to the platform_ make files found in directory
290 pegasus/mak
|
291 mike 1.7
292
293 Note: if you plan on doing parallel builds, you might consider setting
294 PEGASUS_HOME to something like this:
295
|
296 karl 1.11 $HOME/pegasus_home_LINUX_IX86_GNU
|
297 mike 1.7
298 That way, the output of each build will be placed in its own directory.
299
300 3. Now place $PEGASUS_HOME/bin on your path
301
302 and
303
|
304 karl 1.11 Place $PEGASUS_HOME/lib on your LD_LIBRARY_PATH (for Unix only).
305 For RedHat/SuSE/UL, edit /etc/ld.so.conf and add $PEGASUS_HOME/lib
|
306 mike 1.7
|
307 karl 1.11 4. Change to the root of the Pegasus distrubution and type "make"
308 (where make refers to GNU make).
|
309 karl 1.1
|
310 karl 1.11 5. Then create the repository, which is needed to serve data.
|
311 mike 1.9 "make repository"
312
313 6. To test the build type "make tests".
|
314 karl 1.1
|
315 mike 1.7 The following make targets are supported:
|
316 karl 1.1
|
317 mike 1.7 <default> - Build everything.
318 clean - Clean out all objects, libs, and executables.
319 depend - Create the dependencies.
|
320 mike 1.9 repository - Create the repository in $PEGASUS_HOME/repository
|
321 mike 1.7 tests - Execute all tests (except client server tests).
322 rebuild - clean, depend, <default>
323 world - depend, <default>
|
324 karl 1.1
|
325 karl 1.4 The Pegasus Client server tests are executed separately from the above because
326 they require the initiation of separate process for the Pegasus server and
|
327 karl 1.11 Pegasus client. To execute these tests please refer to the scripts in
328 pegasus/mak/BuildMakefile - refer to the prestarttests and poststarttests.
|
329 karl 1.1
|
330 karl 1.4 For information on particular installation characteristics, tools, etc. for
|
331 karl 1.6 each platform see the appropriate sections below:
|
332 karl 1.1
333 Generally the build commands are as follows:
334
|
335 karl 1.6 1. There is a Makefile in the Pegasus root directory. Simply executing
|
336 karl 1.11 make in the Pegasus root directory will make everything. "make rebuild"
|
337 karl 1.6 will clean and rebuild everything. The "make rebuild" will also populate
338 the repository with the current CIM Schemas.
|
339 karl 1.1
|
340 karl 1.6 2. To test a fresh release, go to the pegasus root and type
|
341 karl 1.1
|
342 karl 1.11 "make world".
|
343 karl 1.1
344
|
345 karl 1.6 This will build dependencies, build binaries, and then run all
|
346 karl 1.4 tests except the Client/Server tests.
|
347 karl 1.1
|
348 karl 1.6 3. To execute the basic test suite that is shipped with pegasus type
|
349 karl 1.1
|
350 karl 1.11 "make tests". This also reintalls the repository.
|
351 karl 1.1
|
352 karl 1.4 Running "make -s tests" suppresses extraneous output such as the
353 enter/leave directory messages.
|
354 karl 1.1
|
355 karl 1.11 4. "make clean" removes all object and library files from the structure.
356
357
358 5. A new build system has been added to Pegasus where a new CVS checkout is done,
359 built, and tests are run. Do it by: "make -f mak/BuildMakefile cleanbuild"
360
361
362 8. Populate the Repository
363 ===========================
364
365 Before using Pegasus you must populate the repository with the providers. The makefile
366 does it all for you, but in case you are wondering what it does or how to do it
367 manually:
368
369 1. Register the MOF (Managed Object Format) file describing the skeleton of the object.
370 2. Register a second MOF which only points out which lib*.so file to be loaded when a
371 specific object is activated.
372
373 This is done automatically for the providers included in Pegasus by doing:
374 make repository.
375
376 karl 1.11 The 'make repository' in pegasus/Schemas does three things
377 Runs MOF compiler (cimmofl) on:
378 -Schema v2.7
379 Generates the CIM Schema v2.7 in the repository (skeleton of CIM objects)
380 -PG_InterOp
381 Internal to Pegasus schema for operating (shutdown, add users, etc)
382 CIM_Indication’s (SNMP, Events, Alert, Threshold, etc)
383 -PG_ManagedSystem
384 Registers included CIM Providers (libOSProvider.so, libDNSProvider.so, … )
385 in Pegasus (which are located in src/Providers)
386
387 For more information about using the MOF compiler, refer to user's manual on the
388 openpegasus.org.
|
389 karl 1.1
|
390 karl 1.11
391 9. The MU Utility
392 ===================
|
393 karl 1.1
|
394 karl 1.4 In order to provide a consistent build structure across multiple platforms, we
395 developed a small utility to provide a consistent set of small utilities
396 across these platforms. The MU utilityis a simple utility that contains many
397 commands. For example:
|
398 karl 1.1
399
400 C:\> mu rm myfile.cpp yourfile.cpp
401
402
403 You may type "mu" to get a list of valid commands. Here are some
404 of them:
405
406
|
407 karl 1.2 rm, rmdirhier, mkdirhier, echo, touch, pwd, copy, move, compare depend
|
408 karl 1.1
409
410 The MU utility supports globing (expansion of wildcards) so
411 you can do things like this:
412
413
414 C:\> mu rm *.obj *.exe
415
|
416 karl 1.4 MU is required to build under the Windows environment.MU is available as part
417 of the distribution of Pegasus.
|
418 karl 1.1
419
|
420 karl 1.11 10. Notes about Building Pegasus on Linux
421 ===========================================
422
423 No problem. Just make sure you have the environment variables set.
424
|
425 karl 1.1
|
426 karl 1.11 11. Notes about Building Pegasus with SSL
427 ==========================================
|
428 karl 1.1
|
429 karl 1.11 To build with SSL you need the OpenSSL libraries and header files. Make sure
430 you have them in a standard directory so Pegasus can find them. If that's not
431 the case, set the environment varialble OPENSSL_HOME= to point where your OpenSSL
432 installation is.
433
434 Also have the PEGASUS_HAS_SSL=yes variable set. Then just run 'make' in Pegasus
435 directory and you will have Pegasus with SSL enabled. See section "Creating SSL
436 certificates" for more information of how to use SSL.
437
438
439 12. Building Pegasus on Windows 2000 (SP3 or later recommended) or Windows XP
440 With Microsoft Visual C++
441 ======================================================================
442
443 Today we build Pegasus on Windows using a set of make files contained
444 in the source distribution, the Microsoft compilers (DevStudio 5.x is not
445 supported, Visual Studio 6.0, SP5 supported) and the GNUMAKE make utility.The
446 following is the basic setup steps for the environment.
447
448
449 Setup the environment variables and path for the Micrososft Visual C compiler.
450 karl 1.11 Typically this can be done by running the VCVARS32.BAT file supplied with
451 Microsoft Visual C++. (contained in the same directory as cl.exe).
452
453 For Windows, try the following for an example environment:
454
455 REM call the standard Microsoft .bat for VC 6 setup.
456 call 'C:/Program Files/Microsoft Visual Studio/VC98/Bin/Vcvars32.bat'
457 REM Set debug to something if you want compile in debug mode
458 set PEGASUS_DEBUG=true
459 REM set PEGASUS_ROOT to top of source tree
460 set PEGASUS_ROOT=C:/cimom/pegasus
461 REM set PEGASUS_HOME to where you want repository and executables
462 set PEGASUS_HOME=%PEGASUS_ROOT%
463 REM setup the path to the runtime files.
464 set path=%path%;%PEGASUS_HOME%/bin
|
465 karl 1.1
|
466 karl 1.11 13. Installing the Pegasus HTML Test Client:
467 =============================================
|
468 karl 1.1
|
469 karl 1.4 This is a separate test tool that allows Pegasus requests to be initiated from
470 any WEB browser and that uses a WEB browser, CGI scritps and HTML pages for
471 the formating and connections. It requires a WEB server, etc. The
472 instructions for setting up this environment are maintained in a separate
473 readme in the CGI directory.
|
474 karl 1.1
|
475 karl 1.11
476 14. Development with Pegasus and Pegasus Tools:
477 ================================================
|
478 karl 1.1
479 ATTN: This section needs to be completed. It should reference the more
480 complete documentation
|
481 karl 1.11 ATTN: Write about providers?
|
482 karl 1.1
|
483 karl 1.11
484 15. Commands:
485 =============
486
487 The manpages for each of the commands are in rpm/manLinux/man1.Z directory (on CVS)
488
489 To see simple help for each of the commands, use the "-h" flag.
490 Examples:
491 bin/cimserver –s (Shuts it down)
492 bin/cimserver traceLevel=4 traceComponents=ALL (starts server with config flags)
493 bin/cimprovider –l –s (lists providers and their status)
494 bin/cimprovider –e –m OperatingSystemModule (enables the OperatingSystem provider)
495 bin/cimuser –a –u guest –w ThePassword
496 bin/cimuser –l (lists the users)
497 bin/tomof CIM_Config (extract CIM_Config from repository and present it in MOF type)
498
499
500 16. Creating SSL certifications
501 ================================
502
503 Type these commands in your shell to create the SSL certifications. The PEGASUS_ROOT
504 karl 1.11 and PEGASUS_HOME have to be set to your respective installation and source directory.
505
506 CN="Common Name"
507 EMAIL="test@email.address"
508 HOSTNAME=`uname -n`
509 sed -e "s/$CN/$HOSTNAME/" \
510 -e "s/$EMAIL/root@$HOSTNAME/" $PEGASUS_ROOT/ssl.cnf \
511 > $PEGASUS_HOME/ssl.cnf
512 chmod 644 $PEGASUS_HOME/ssl.cnf
513 chown bin $PEGASUS_HOME/ssl.cnf
514 chgrp bin $PEGASUS_HOME/ssl.cnf
515
516 /usr/bin/openssl req -x509 -days 365 -newkey rsa:512 \
517 -nodes -config $PEGASUS_HOME/ssl.cnf \
518 -keyout $PEGASUS_HOME/key.pem -out $PEGASUS_HOME/cert.pem
519
520 cat $PEGASUS_HOME/key.pem $PEGASUS_HOME/cert.pem > $PEGASUS_HOME/server.pem
521 rm $PEGASUS_HOME/key.pem $PEGASUS_HOME/cert.pem
522 cp $PEGASUS_HOME/cert.pem $PEGASUS_HOME/client.pem
523
524
525 karl 1.11 17. Documentation:
526 ===================
|
527 karl 1.1
|
528 karl 1.4 The documentation is currently in preperation. The preliminary documentation
529 is not provided with this snapshot but is avialable from the OpenGroup Pegasus
530 WEB pages. The current documentation is maintained both as a manual created
|
531 karl 1.5 under the tool DOC++ in the runtime subdirectory manual/html and as other
532 miscelaneous documentation in the doc directory.
|
533 karl 1.4
534 Note that the Pegasus WEB site at The Open Group will be the source of most
535 documentation in the future and today is the source of most discussion and
536 design documentation.
|
537 karl 1.1
|
538 karl 1.11
539 18. Participate!
540 =================
|
541 mike 1.7
|
542 karl 1.4 We are looking for people who want to join the Pegasus work group and
|
543 karl 1.11 contribute to effort of getting this Pegasus off the ground. Please join
544 the mailing list by visiting www.openpegasus.org, and click on Mailing Lists.
|