1 karl 1.1 <html>
2
3 <head>
4 <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
5 <meta name="ProgId" content="FrontPage.Editor.Document">
6 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
7 <title>OpenPegasus</title>
8 </head>
9
10 <body>
11
12 <p align="center"><b><font size="4">Pegasus Enhancement Proposal (PEP)</font></b></p>
13 <p style="margin-top: 0; margin-bottom: 0"><b>PEP #:</b> 103</p>
14 <p style="margin-top: 0; margin-bottom: 0"><b>Title: </b>OpenPegasus Version 2.3
15 Release Readme file</p>
16 <p style="margin-top: 0; margin-bottom: 0"><b>Version: </b>1.0</p>
17 <p style="margin-top: 0; margin-bottom: 0"><b>Created:</b> 12 November 2003</p>
18 <p style="margin-top: 0; margin-bottom: 0"><b>Authors: </b>Karl Schopmeyer</p>
19 <p style="margin-top: 0; margin-bottom: 0"><b>Status: </b>draft</p>
20 <p style="margin-top: 0; margin-bottom: 0"><b>Version History:</b></p>
21 <table border="1" cellspacing="1" bordercolordark="#666666"
22 karl 1.1 bordercolorlight="#CCCCCC" width=100%
23 style='font-size=10.0pt;font-family:Arial'>
24 <tr>
25 <th bgcolor="#CAE6CA">Version</th>
26 <th bgcolor="#CAE6CA">Date</th>
27 <th bgcolor="#CAE6CA">Author</th>
28 <th bgcolor="#CAE6CA">Change Description</th>
29 </tr>
30 <tr>
31 <td align="center">1.0</td>
32 <td align="center">12 Novemberl 2003</td>
33 <td align="center">Karl Schopmeyer</td>
34 <td>Update from 2.2 Release notes. Converted to HTML</td>
35 </tr>
36 <tr>
37 <td align="center"> </td>
38 <td align="center"> </td>
39 <td align="center"> </td>
40 <td> </td>
41 </tr>
42 </table>
43 karl 1.1 <hr>
44 <p><b>Abstract:</b> Installation, build, operation information on the
45 Pegasus Platform Version 2.3 Release. Note that if this readme conflicts with
46 the documentation in the release notes or interface defintion documents for a
47 particular release, those documents should be considered authorative. This is a
48 simplified overview to act as an introduction to Pegasus.</p>
49 <hr>
50
51 <p align="Center"><b><font size="5">OpenPegasus - A Manageability Services Broker
52 for the DMTF CIM/WBEM Standards
53 </font>
54 </b>
55
56 <p align="left">
57 <b>Tagline:</b> OpenPegasus is an object manager for DMTF CIM objects written in C++
58 and supported by The Open Group </p>
59
60 <p align="left">
61
62 <b>STATUS:</b> Revised October 2003 for Pegasus release version 2.3.
63 </p>
64 karl 1.1
65 <p align="center">
66 <b><font size="4">Table of Contents</font></b><p align="left" style="margin-top: 0; margin-bottom: 0">
67 <a href="#Overview"> Overview</a>
68
69 <p align="left" style="margin-top: 0; margin-bottom: 0">
70 <a href="#Availability of Pegasus">Availability of Pegasus</a><p align="left" style="margin-top: 0; margin-bottom: 0">
71 <a href="#Pegasus Major Components">Pegasus Major Components</a><p align="left" style="margin-top: 0; margin-bottom: 0">
72 <a href="#Pegasus Supported Platforms">Pegasus Supported Platforms</a><p align="left" style="margin-top: 0; margin-bottom: 0">
73 <a href="#Pegasus Dependencies">Pegasus Dependencies </a>
74
75 <p align="left" style="margin-top: 0; margin-bottom: 0">
76 <a href="#The Pegasus Directory Structure">The Pegasus Directory Structure</a>
77
78 <p align="left" style="margin-top: 0; margin-bottom: 0">
79 <a href="#Pegasus Installation">Installation</a>
80
81 <p align="left" style="margin-top: 0; margin-bottom: 0">
82 <a href="#Building Pegasus">Building Pegasus </a>
83
84 <p align="left" style="margin-top: 0; margin-bottom: 0">
85 karl 1.1 <a href="#Populate the Repository">Populate the Repository</a>
86
87 <p align="left" style="margin-top: 0; margin-bottom: 0">
88 <a href="#Registering Providers in the Pegasus Environment">Registering
89 Providers</a><p align="left" style="margin-top: 0; margin-bottom: 0">
90 <a href="#The MU Utility">The MU Utility</a>
91
92
93 <p align="left" style="margin-top: 0; margin-bottom: 0">
94 <a href="#Notes about Building Pegasus on Linux">Notes about Building Pegasus on Linux</a>
95
96 <p align="left" style="margin-top: 0; margin-bottom: 0">
97 <a href="#Notes about Building Pegasus with SSL">Notes on building Pegasus with SSL</a>
98
99 <p align="left" style="margin-top: 0; margin-bottom: 0">
100 <a href="#Building Pegasus on Windows 2000 or Windows XP With Microsoft Visual C++">Building Pegasus on Windows 2000 or Windows XP With Microsoft Visual C++</a><p align="left" style="margin-top: 0; margin-bottom: 0">
101 <a href="#Installing the Pegasus HTML Test Client">Installing the Pegasus HTML Test Client
102 </a>
103
104 <p align="left" style="margin-top: 0; margin-bottom: 0">
105 <a href="#Development with Pegasus and Pegasus Tools">Development with Pegasus and Pegasus Tools</a>
106 karl 1.1
107 <p align="left" style="margin-top: 0; margin-bottom: 0">
108 <a href="#Commands">Commands</a>
109
110 <p align="left" style="margin-top: 0; margin-bottom: 0">
111 <a href="#Creating SSL certifications">Creating SSL certifications</a>.
112
113 <p align="left" style="margin-top: 0; margin-bottom: 0">
114 <a href="#Testing with ICU enabled">Testing with ICU enabled </a>
115
116 <p align="left" style="margin-top: 0; margin-bottom: 0">
117 <a href="#Pegasus Documentation">Documentation</a>
118
119 <p align="left" style="margin-top: 0; margin-bottom: 0">
120 <a href="#Participate!">Participate</a>
121
122 <h1><a name="Overview">Overview</a> </h1>
123
124 <p>OpenPegasus (also referred to as Pegasus):
125
126 Pegasus is an open-source object manager (CIMOM) for DMTF CIM objects. It is written
127 karl 1.1 in C++ and includes the Object manager, a set of defined interfaces, and
128 Interface libraries
129 for both client and providers. It is maintained
130 consistent with the DMTF CIM and WBEM specifications except for exceptions
131 noted in the documentation.
132 <P>
133 Pegasus is open source and is covered under the MIT open-source license.
134 <P>
135 Pegasus is being developed and maintained under the auspices of The Open
136 Group. Pegasus is maintained under the license defined in the doc directory
137 (LICENSE) of this release. This licensing is intended to support as wide a
138 distribution as possible with minimal demands on the users.
139 <P>
140 More information on this project, access to the CVS, and documentation on
141 Pegasus are available from the OpenGroup WEB site.
142 <P>
143 <a href="http://www.opengroup.org">http://www.openpegaus.org</a><p>
144 There are separate documents
145 <ul>
146 <li>What's new for this release - WHATSNEW and the release notes for each
147 release.<li>What's Broken - BUGS - See the ReleaseNotes for this release in the CVS and
148 karl 1.1 the web site as a Pegasus PEP.<li>Release Notes for each released version</ul>
149
150
151 <p>The release notes are available on the WEB site as Pegasus PEP documents and
152 in the CVS for each release.</p>
153 <table border="1" cellspacing="1" width="31%" id="AutoNumber3">
154 <tr>
155 <td width="42%">Release</td>
156 <td width="58%">Release Notes PEP</td>
157 </tr>
158 <tr>
159 <td width="42%">2.0</td>
160 <td width="58%">None</td>
161 </tr>
162 <tr>
163 <td width="42%">2.1</td>
164 <td width="58%">None</td>
165 </tr>
166 <tr>
167 <td width="42%">2.2</td>
168 <td width="58%">PEP 57</td>
169 karl 1.1 </tr>
170 <tr>
171 <td width="42%">2.3</td>
172 <td width="58%">PEP 98</td>
173 </tr>
174 </table>
175
176
177 <h1><a name="Availability of Pegasus">Availability of Pegasus</a></h1>
178
179 <p>Pegasus is distributed as open source under the MIT open-source license. The distribution is available via
180 CVS and snapshot images in tar and zip file formats.
181 The source code from CVS can be found at the following Open Group CVS server;
182 <p>
183 <font face="Courier New">
184 cvs.opengroup.org:/cvs/MSB </font>
185 <p>
186 using the password authenticating server option (pserve).
187 <p>
188 Anonymous access for read is with the name and password "anon" as follows:
189 <blockquote>
190 karl 1.1 <p style="margin-top: 0; margin-bottom: 0">
191 <font face="Courier New">%export CVSROOT=:pserver:anon@cvs.opengroup.org:/cvs/MSB
192 </font>
193 <p style="margin-top: 0; margin-bottom: 0"><font face="Courier New">%cvs login
194 </font>
195 </blockquote>
196 <p>
197 When requested, enter the password "anon".
198 The source tree is in the directory pegasus. To check out the complete Pegasus
199 source tree just type:
200 <p>
201 <font face="Courier New">
202 cvs co pegasus </font>
203 <p>
204 A Pegasus directory will be created under the current directory and populated
205 with the complete source tree and documentation. To get the latest updates
206 after a checkout just type this from Pegasus root:
207 <p>
208 <font face="Courier New">
209 cvs update -d </font>
210
211 karl 1.1 <p>
212 Active contributors to Pegasus have write access to the CVS repository.
213 If you are interested in contributing back to the Pegasus project,
214 (i.e. write (checkin) access to CVS) please request access from either
215 Martin Kirk (m.kirk@opengroup.org) or Karl Schopmeyer
216 <a href="mailto:(k.schopmeyer@opengroup.org">(k.schopmeyer@opengroup.org</a>).
217
218 <h1>
219 <a name="Pegasus Major Components">Pegasus Major Components</a></h1>
220
221 <p>The major components of Pegasus are:
222 <ul>
223 <li><b>Pegasus Server</b> - WBEM/CIM Server with interfaces for providers and clients
224 </li>
225 <li><b>Pegasus Repositories</b> - Today Pegasus provides a defined class repository
226 interface and a simple file based class repository. It also includes
227 an instance repository. Note that these repository were created for
228 functionality, not efficieny. It is expected that they will be replaced
229 with other implementations of the respository function as the need arises.
230 </li>
231 <li><b>Pegasus Client Library</b> - Tools for building Pegasus clients based on the Pegasus
232 karl 1.1 C++ interfaces and using the WBEM HTTP/XML protocols or directly
233 interfacing with Pegasus.
234 </li>
235 <li><b>Pegasus Test Clients</b> - Simple test clients being developed as part of the
236 Pegasus development process
237 </li>
238 <li><b>Pegasus HTML Test Client</b> - To aid in testing we created a test client for
239 Pegasus that uses a WEB server (ex. Apache) with a set of CGI modules and
240 HTML to allow the entry of Pegasus operations from a WEB browser as forms
241 and the receipt of the response as WEB pages. This has proven useful as a
242 test tool and can be used for a wide variety of demonstrations.
243 </li>
244 <li><b>Pegasus Provider Library</b> - Tools for building Pegasus providers using the Pegasus
245 C++ interfaces.
246 </li>
247 <li><b>Pegasus Providers</b> - Providers to illustrate the use of Pegasus services
248 including providers for test and demonstration.
249 </li>
250 <li><b>Pegasus Control Providers</b> - Common services for use by other Pegasus
251 components to extend Pegasus capabilites.
252 </li>
253 karl 1.1 <li><b>Pegasus MOF Compiler </b>- There standalone compiler (cimmofl) for MOF files that can be used
254 to install MOF into the Pegasus schema repository and also to check syntax.
255 There is also a compiler that operates as a Pegasus client(cimmof)
256 There is also a tool to extract the MOF from the repository.
257
258 </li>
259 </ul>
260
261 <h1>
262 <a name="Pegasus Supported Platforms">Pegasus Supported Platforms</a></h1>
263
264 <p>
265 Pegasus is regularly tested against a variety of platforms by the development
266 group. The set of platforms and exact set of compilers for any given
267 release is documented in the Release notes for that release (see the CVS source
268 tree root directory or the Pegasus PEP defining the ReleaseNotes for any
269 particular release).</p>
270
271 <p>
272 Generally Pegasus is supported on the following Platforms and Compilers.</p>
273 <table border="1" cellspacing="1" id="AutoNumber2" width="728">
274 karl 1.1 <tr>
275 <td width="169" bgcolor="#99FF99"><b>Platform and OS</b></td>
276 <td width="556" bgcolor="#99FF99"><b>Compilers</b></td>
277 </tr>
278 <tr>
279 <td width="169">AIX</td>
280 <td width="556">VisualAge C++ Version</td>
281 </tr>
282 <tr>
283 <td width="169">HP-UX</td>
284 <td width="556">HP aC++ </td>
285 </tr>
286 <tr>
287 <td width="169">Linux Itanium</td>
288 <td width="556">gcc</td>
289 </tr>
290 <tr>
291 <td width="169">Linux IA-32</td>
292 <td width="556">gcc (versions 2.9x and 3.xx)</td>
293 </tr>
294 <tr>
295 karl 1.1 <td width="169">Windows 2000</td>
296 <td width="556">Microsoft Visual C++ Ver 6 and Microsoft .Net compiler
297 Version <font color="#FF0000">7</font></td>
298 </tr>
299 <tr>
300 <td width="169">Windows XP</td>
301 <td width="556">Microsoft Visual C++ Ver. 6 and Microsoft .Net compiler
302 Version <font color="#FF0000">7</font></td>
303 </tr>
304 </table>
305
306 <h1>
307 <a name="Pegasus Dependencies">Pegasus Dependencies </a></h1>
308
309 <p>
310 We have worked to minimize the dependence of Pegasus on other software
311 packages and tools. Currently Pegasus has the following dependencies:
312 <p>
313 <b>1. GNUMAKE</b> - To simplify the building of Pegasus across multiple platforms we
314
315 have standardized on a set of build tools including: GNUMAKE. We are using
316 karl 1.1 GNUMAKE 3.79.1 successfully both in Windows and Linux environments.
317 <p>
318 GNUMAKE is available from :<p>
319 <a href="http://www.gnu.org">http://www.gnu.org</a>
320
321 <p>
322 NOTE: A set of the required tools for
323 windows platforms is available on the openpegasus web site.<p>
324 <b>2. MU.EXE </b>- To minimize the difference between Linux and Windows for GNUMAKE,
325 we have created a utility called MU.exe. This utility is required for
326 Pegasus make with ONLY Windows environment. It is provided as an alternative to
327 requiring a number of UNIX utilities (SH, RM, etc.) on the windows platform
328 and effectively provides the functions of these utilities that GNUMAKE
329 needs. MU is not required on UNIX or LINUX platforms.
330 <p>
331 NOTE: The binary for MU.EXE is not distributed in the Pegasus bin directory.
332 You must build it separately. MU source code is part of the distribution
333 in the directory src/utils/MU with its own make file. You must compile MU
334 before you initiate the Pegausu make.
335 <p>
336 NOTE: A copy of the binary is made available as a zip file on the Pegasus
337 karl 1.1 WEB site.
338 <p>
339 Again, MU is used ONLY if you are using Windows.
340
341 <p>
342 <b>3. FLEX and BISON</b> - These tools were used to develop the MOF compiler and WQL
343 parser. Anybody intending to recompile the compiler or parser from scratch
344 will be required to have these tools. They are only required if changes need
345 to be made to the files for parsing and compiling.
346 <p><b>4. DOC++ </b>- The Pegasus documentation is taken from a combination of text files
347 and the Pegasus header files themselves. This documentation is formatted
348 with DOC++ and GAWK. These tools are required if the documentation is to
349 be recreated but we expect that only the core team will be recreating
350 documentation.
351
352 <p><b>5. ICU Internationalization libraries</b> - These libraries are used as
353 the basis for message catalogs for message internationalization. See the ICU
354 website (http://oss.software.ibm.com/icu/) for more information on these
355 libraries<p>6. <b>OpenSSL </b>- If it is intended to use SSL on the
356 communication protocol, the OpenSSL libraries are required.<h1>
357 <a name="The Pegasus Directory Structure">The Pegasus Directory Structure</a></h1>
358 karl 1.1 <p>
359 Pegasus is distributed as a complete source directory structure that should be
360 installed either from one of the snapshots or from CVS.
361 <p>
362 This structure is generally as follows:<p>
363 <font face="Courier New">Pegasus Source Structure</font><p>
364 <font face="Courier New">Pegasus Root directory (PEGASUS_ROOT environment
365 variable)</font><ul>
366 <li><font face="Courier New"><b>cgi</b> Source for the Pegasus WEB Based Test client
367 </font>
368 <ul>
369 <li><font face="Courier New">cgi-bin CGI Directories for WEB demonstration.
370 This directory is normally empty but can
371 be populated from the runtime with the make
372 from cgi.
373 </font></li>
374 <li><font face="Courier New">htdocs HTML Pages for Pegasus WEB demonstration
375 </font></li>
376 </ul>
377 </li>
378 <li><font face="Courier New"><b>doc</b> Miscellaneous Pegasus Documents.
379 karl 1.1 </font>
380 <ul>
381 <li><font face="Courier New">apidoc - Source for the public api
382 documentation.</font></li>
383 <li><font face="Courier New">DevManual Source and build files for developers' manual
384 mak General make files (used by other makes)</font></li>
385 </ul>
386 </li>
387 <li><font face="Courier New"><b>mak</b> - Common make files for Pegasus
388 compilation</font></li>
389 <li><font face="Courier New"><b>Dummy</b> -</font></li>
390 <li><font face="Courier New"><b>InterfaceArchive</b> -</font></li>
391 <li><font face="Courier New"><b>rpm</b> - files for rpm installation for Linux</font></li>
392 <li><font face="Courier New"><b>Schemas</b> - Schemas used in the installation
393 of Pegasus. This includes currently released versions of the DMTF schemas in
394 subdirectories (ex. CIM27) and Pegasus local Schemas (ex. </font></li>
395 <li><font face="Courier New"><b>src</b> All Pegasus Source Files
396 </font>
397 <ul>
398 <li><font face="Courier New"><b>ACEExample</b> Test directrory with examples of the use of ACE (obsolete).
399 </font></li>
400 karl 1.1 <li><font face="Courier New"><b>Clients</b> Source for various test
401 clients and demonstration clients.</font></li>
402 <li><font face="Courier New"><b>CGICLIENT</b> Pegasus test client that uses a WEB browser
403 JAVA Java Client support modules
404 </font></li>
405 <li><font face="Courier New"><b>Pegasus</b> - Core pegasus modules.
406 </font>
407 <ul>
408 <li><font face="Courier New"><b>Client</b> Pegasus Client API Tests
409 depends tests </font></li>
410 <li><font face="Courier New"><b>Common</b> Pegasus Common Functions (C++ source and headers
411 tests Test programs for the common functions</font></li>
412 <li><font face="Courier New"><b>Compiler</b> Pegasus MOF compiler
413 </font></li>
414 <li><font face="Courier New"><b>Config</b> Pegasus Configuration
415 functions</font></li>
416 <li><font face="Courier New"><b>Consumer</b> TBD </font></li>
417 <li><font face="Courier New"><b>ControlProviders</b> Implementation of Pegasus internal providers
418 </font></li>
419 <li><font face="Courier New"><b>ExportClient</b> TBD
420 </font></li>
421 karl 1.1 <li><font face="Courier New"><b>ExportServer</b> TBD
422 </font></li>
423 <li><font face="Courier New"><b>Handler</b> TBD </font></li>
424 <li><font face="Courier New"><b>HandlerService</b> TBD
425 </font></li>
426 <li><font face="Courier New"><b>IndicationService</b> TBD
427 </font></li>
428 <li><font face="Courier New"><b>Listener</b> TBD </font></li>
429 <li><font face="Courier New"><b>Protocol</b> Pegasus Client HTTP/XML Protocol Modules
430 depends </font></li>
431 <li><font face="Courier New"><b>Provider</b> Pegasus Provider interface functions
432 </font></li>
433 <li><font face="Courier New"><b>ProviderManager</b> Provider Manager service that manages providers
434 </font></li>
435 <li><font face="Courier New"><b>ProviderManager2</b> Pluggable Provider Manager service.
436 Today this is not enabled by default It will become the Pegasus
437 standard provider manager at some time in the future but for now, see
438 the release notes if you want to enable it.</font></li>
439 <li><font face="Courier New"><b>Repository</b> Pegasus Repository
440 Interfaces and Simple Repository tests </font>
441 <ul>
442 karl 1.1 <li><font face="Courier New">Tests for Repository Functions </font>
443 </li>
444 </ul>
445 </li>
446 <li><font face="Courier New"><b>Security</b> TBD </font></li>
447 <li><font face="Courier New"><b>Server</b> Pegasus Server Modules
448 </font></li>
449 <li><font face="Courier New"><b>WQL</b> TBD
450 </font></li>
451 </ul>
452 </li>
453 </ul>
454 </li>
455 <li><font face="Courier New"><b>Providers</b> Pegasus test and required providers
456 </font>
457 <ul>
458 <li><font face="Courier New"><b>generic</b> TBD this and following IndicationConsumer
459 </font></li>
460 <li><font face="Courier New"><b>Linux</b> </font></li>
461 <li><font face="Courier New"><b>ManagedSystem</b> Providers
462 associated with managing the Pegasus System</font></li>
463 karl 1.1 <li><font face="Courier New"><b>slp</b> - </font></li>
464 <li><font face="Courier New"><b>statistic</b> - Providers for
465 Pegasus statistics.</font></li>
466 <li><font face="Courier New"><b>sample</b> Sample providers for the
467 major provider types.</font></li>
468 <li><font face="Courier New"><b>testproviders</b> </font></li>
469 </ul>
470 </li>
471 <li><font face="Courier New"><b>Server</b> Pegasus executable build
472 </font></li>
473 <li><font face="Courier New"><b>slp</b> - TBD</font></li>
474 <li><font face="Courier New"><b>Standard Includes</b> - TBD</font></li>
475 <li><font face="Courier New"><b>test</b> - Directory of end-end
476 tests that are regularly conducted on Pegasus</font></li>
477 <li><font face="Courier New"><b>tools</b> MU and other utilities written for Pegasus support
478 </font></li>
479 <li><font face="Courier New"><b>Unsupported</b> Code that is made available but is not supported or included
480 in the normal make. </font></li>
481 <li><font face="Courier New"><b>WMIMapper</b> Pegasus implementation that implements mapping to Microsoft
482 WMI objects.
483
484 karl 1.1 </font></li>
485 </ul>
486 <p>
487 <font face="Courier New">Pegasus Run Time directory structure (PEGASUS_HOME
488 environment variable). Home directory for runtime. All compiler, linker
489 documentation creation, etc. are put here.
490 </font>
491 <ul>
492 <li><font face="Courier New"><b>bin</b> - Destination for executable and DLL modules from
493 Pegasus build. This directory should be make public so that the test functions,
494 clients, and cimserver can be executed with minimum effort.</font></li>
495 <li><font face="Courier New"><b>DevManualHTML</b> - HTML output of the Pegasus Manual.
496 This is only created when the make file for this manual is
497 executed (doc/DevManual) and then contains the html representing
498 the document.</font></li>
499 <li><font face="Courier New"><b>apidochtml</b> - HTML output of
500 the creation of the public API document. This only exists
501 when the make file for the api document is executed (see doc/apidoc/Makefile)</font></li>
502 <li><font face="Courier New"><b>lib</b> - Destination for Pegasus LIB modules
503 </font></li>
504 <li><font face="Courier New"><b>log</b> - Standard location for
505 karl 1.1 Pegasus Logs</font></li>
506 <li><font face="Courier New"><b>obj</b> - Destination for object
507 modules. Note that today, the trace file is located in the
508 PEGASUS_HOME directory, not in the log directory if Pegasus
509 internal tracing is enabled.</font></li>
510 <li><font face="Courier New"><b>repository</b> - This Directory
511 contains the created repository </font></li>
512 </ul>
513
514 <h1>
515 <a name="Pegasus Installation">Pegasus Installation</a> </h1>
516 <p>
517 Pegasus today is provided only as a source distribution.
518 <p>
519 To install Pegasus, you must check it out using CVS (Common Version System)
520 or download a snapshot. You download, compile, and use it.
521 <p>
522 For the snapshot, the installation of Pegasus involves expanding the snapshot
523 distribution files, building the runtime, the test files and test clients, and
524 building the repository.
525 <h1>
526 karl 1.1
527 <a name="Building Pegasus">Building Pegasus </a>
528
529 </h1>
530
531 <p>
532 1. Check that you have requisite programs (listed in Pegasus Dependencies).
533
534 These include GNU Make, MU.EXE (if using Windows), Flex, and Bison (Flex
535 and Bison only required if changes will be made to the MOF compiler or WQL
536 parser).
537 <p>
538 Be sure these are on the path.
539
540 <p>
541 2. Define the following three environment variables:
542 <ul>
543 <li><b>PEGASUS_ROOT</b> - this should be the "pegasus" directory you've pulled from CVS
544 </li>
545 <li><b>PEGASUS_HOME</b> - to point to a directory to contain output binary files
546 (e.g., set it to $HOME/pegasus_home). Then the output will go into
547 karl 1.1 $HOME/pegasus_home/bin and $HOME/pegasus_home/lib
548 </li>
549 <li><b>PEGASUS_PLATFORM</b> - this must be set to a supported platform identifier.
550 </li>
551 </ul>
552 <blockquote>
553 <p>
554 This identifier has the following form:
555 <p>
556 <font face="Courier New">
557 <Operating-System>_<Architecture>_<Compiler> </font>
558 <p>
559 For example (Linux on IA32 platform using the GNU Compiler):
560 LINUX_IX86_GNU
561 <p>
562 For a complete list of platforms supported and platform support keywords, refer to the platform_ make files found in directory
563 <font face="Courier New">pegasus/mak</font>
564
565 </blockquote>
566
567 <p>
568 karl 1.1 Note: if you plan on doing parallel builds, you might consider setting
569 PEGASUS_HOME to something like this:
570 <p>
571 <font face="Courier New">
572 $HOME/pegasus_home_LINUX_IX86_GNU </font>
573 <p>
574 That way, the output of each build will be placed in its own directory.
575 <p>
576 3. Now place $PEGASUS_HOME/bin on your path
577 <p> and
578 <p>
579
580 Place $PEGASUS_HOME/lib on your LD_LIBRARY_PATH (for Unix only).
581 For RedHat/SuSE/UL, edit /etc/ld.so.conf and add $PEGASUS_HOME/lib
582 <p>
583 4. Change to the root of the Pegasus distrubution and type "make"
584 (where make refers to GNU make).
585 <p>
586 5. Then create the repository, which is needed to serve data.
587 "make repository". Note that to create the additional namespaces, etc.
588 that represent the test support you can also execute "make testrepository:<p>
589 karl 1.1 6. To test the build type "make tests".
590 The following make targets are supported:
591 <UL>
592 <li><default> - Build everything.
593 <li>clean - Clean out all objects, libs, and executables.
594 <li>depend - Create the dependencies.
595 <li>repository - Create the repository in $PEGASUS_HOME/repository
596 <li>tests - Execute all tests (except client server tests).
597 <li>rebuild - clean, depend, <default>
598 <li>world - depend, <default>
599 </UL>
600 The Pegasus Client server tests are executed separately from the above because
601 they require the initiation of separate process for the Pegasus server and
602 Pegasus client. To execute these tests please refer to the scripts in
603 pegasus/mak/BuildMakefile - refer to the prestarttests and poststarttests.
604 <p>
605 For information on particular installation characteristics, tools, etc. for
606 each platform see the appropriate sections below:
607 <p>
608 Generally the build commands are as follows:
609 <ol>
610 karl 1.1 <li>There is a Makefile in the Pegasus root directory. Simply executing
611 make in the Pegasus root directory will make everything. "make rebuild"
612 will clean and rebuild everything. The "make rebuild" will also populate
613 the repository with the current CIM Schemas.
614 </li>
615 <li>To test a fresh release, go to the pegasus root and type
616 "<font face="Courier New">make world</font>".
617 This will build dependencies, build binaries, and then run all
618 tests except the Client/Server tests.
619 </li>
620 <li>To execute the basic test suite that is shipped with pegasus type
621 "make tests". This also reinstalls the repository.
622 Running "make -s tests" suppresses extraneous output such as the
623 enter/leave directory messages.
624 </li>
625 <li>"make clean" removes all object and library files from the structure.
626
627 </li>
628 <li>A new build system has been added to Pegasus where a new CVS checkout is
629 done,
630 built, and tests are run. Do it by: "make -f mak/BuildMakefile cleanbuild"
631 karl 1.1
632 </li>
633 </ol>
634
635 <h1>
636 <a name="Populate the Repository">Populating the Pegasus Repository</a> </h1>
637
638 <p>
639 Before using Pegasus you must populate the repository.. The makefile
640 does it all for you, but in case you are wondering what it does or how to do it
641
642 manually:
643 <ol>
644 <LI>Register the MOF (Managed Object Format) file describing the skeleton of the
645 object.
646 <li>Register a second MOF which only points out which lib*.so file to be loaded
647 when a
648 specific object is activated.
649 </ol>
650 This is done automatically for the providers included in Pegasus by doing:
651 make repository.
652 karl 1.1 <p>
653 The 'make repository' in pegasus/Schemas does three things
654 Runs MOF compiler (cimmofl) on:
655 -Schema v2.7
656 Generates the CIM Schema v2.7 in the repository (skeleton of CIM objects)
657 -PG_InterOp
658 Internal to Pegasus schema for operating (shutdown, add users, etc)
659 CIM_Indication’s (SNMP, Events, Alert, Threshold, etc)
660 -PG_ManagedSystem
661 Registers included CIM Providers (libOSProvider.so, libDNSProvider.so, … )
662 in Pegasus (which are located in src/Providers)
663 <p>
664 For more information about using the MOF compiler, refer to user's manual on the
665
666 openpegasus.org.
667
668 <h1>
669 <a name="Testing a Pegasus Installation">Testing a Pegasus Installation</a></h1>
670 <p>
671 Pegasus includes an extensive set of test facilities as part of the CVS
672 enviromentthat can be executed including:<ul>
673 karl 1.1 <li><b>Test Clients</b> - There are several clients that have been built
674 specifically to test Pegasus or parts of Pegasus including TestClient, Client,
675 CLI, ipinfo, osinfo, WbemEsec, etc. See the src/Clients directory for more
676 information. These programs require a server complete with repository to be
677 running. Note that some of these tests use classes and instances that
678 are only installed with the "make testrepository" functions including test
679 namespaces and extra classes and instances in those namespaces and additional
680 providers from the providers/sample and proviers/testproviders directories.</li>
681 <li><b>Sample and test providers</b> - Test providers exist for the
682 major provider types in the providers/sample directories and the providers/testProviders
683 directory</li>
684 <li><b>Unit Tests</b> - Most Pegasus functions include unit tests for the
685 functions. These are normally executed with the "make tests" command
686 which can be executed at many different levels of the source tree from the top
687 level to execute all of the unit tests to individual directories.
688 Usually the unit test functions can be found in test directories immediately
689 below their corresponding source code (i.e common/tests is the unit test
690 functions for the common directory). Unit tests are executed without the
691 server being operational and normally do not require the existence of a Class
692 repository.</li>
693 <li><b>An end-to-end Test Suite</b> - the directory "test" contains a set of
694 karl 1.1 operations tests that cover the major CIM operations. See the make file
695 TestMakefile in the PEGASUS_ROOT directory to execute these tests. This
696 set of tests executes an extensive set of fixed tests and compares the results
697 against predefined results.</li>
698 </ul>
699
700 <h1>
701 <a name="Registering Providers in the Pegasus Environment">Registering Providers
702 in the Pegasus Environment</a></h1>
703
704 <p>
705 Pegasus registers providers with a set of provider registration classes, not
706 using the provider qualifier as is done in most DMTF CIM CIMOM implementations
707 today. This set of classes is close to but not exactly the same as the current
708 DMTF definition (See the DMTF Interop schema, experimental versions starting
709 with 2.6). This will be harmonized in the future when the DMTF scheme is moved
710 to final status. </p>
711
712 <p>
713 Registration is performed by defining a MOF for the instances of the
714 registration classes that represent the porvider module, providers, classes,
715 karl 1.1 etc. to be registered. The easiest way to create a new registration today
716 is to copy from one of the existing registration MOFs. See the
717 providers/sample/load directory for examples of several registration instance
718 implementations that do work with Pegasus today.</p>
719
720 <h1>
721 <a name="The MU Utility">The MU Utility </a></h1>
722
723 <p>
724 In order to provide a consistent build structure across multiple platforms, we
725 developed a small utility to provide a consistent set of small utilities
726 across these platforms. The MU utilityis a simple utility that contains many
727 commands. For example:
728
729 <p>
730 <font face="Courier New">
731 C:\> mu rm myfile.cpp yourfile.cpp </font>
732
733 <p>
734 You may type "mu" to get a list of valid commands. Here are some
735 of them:
736 karl 1.1
737 <p>
738
739 rm, rmdirhier, mkdirhier, echo, touch, pwd, copy, move, compare depend
740
741 <p>
742 The MU utility supports globing (expansion of wildcards) so
743 you can do things like this:
744 <p>
745
746 <font face="Courier New">
747
748 C:\> mu rm *.obj *.exe </font>
749 <p>
750 MU is required to build under the Windows environment. MU is available as part
751 of the distribution of Pegasus.
752
753 <h1>
754 <a name="Notes about Building Pegasus on Linux">Notes about Building Pegasus on
755 Linux </a></h1>
756 <p>
757 karl 1.1 No problem. Just make sure you have the environment variables set (PEASUS_HOME,
758 PEGASUS_ROOT, PEGASUS_PLATFORM. For 32 bit linux, the defintion of
759 PEGASUS_PLATFORM is normally LINUX_IX86_GNU.
760
761 <h1><a name="Notes about Building Pegasus with SSL">Notes about Building Pegasus with SSL
762 </a></h1>
763 <p>
764 To build with SSL you need the OpenSSL libraries and header files. They are NOT
765 distributed with Pegasus. Make sure
766 you have them in a standard directory so Pegasus can find them. If that's not
767
768 the case, set the environment variable OPENSSL_HOME= to point where your
769 OpenSSL
770 installation is.
771 <p>
772 Also have the PEGASUS_HAS_SSL=yes variable set. Then just run 'make' in Pegasus
773 directory and you will have Pegasus with SSL enabled. See section "Creating SSL
774
775 certificates" for more information of how to use SSL.
776
777 <h1>
778 karl 1.1 <a name="Building Pegasus on Windows 2000 or Windows XP With Microsoft Visual C++">
779 Building Pegasus on Windows 2k or Windows XP with Microsoft Visual C++ </a></h1>
780
781 <p>
782 Use of Windows 2000 SP3 or later is recommended. Pegasus is regularly
783 tested on both Windows 2000 and Windows XP using the Microsoft compilers.<p>
784 Today we build Pegasus on Windows using a set of make files contained
785 in the source distribution, the Microsoft compilers (DevStudio 5.x is not
786 supported, Visual Studio 6.0, SP5 is supported) and the GNUMAKE make utility.
787 Note that you MUST have the Pegasus <a href="#The MU Utility">mu.exe </a>utility
788 compiled and available before trying to compile Pegasus on the normal windows
789 platform. The
790
791 following is the basic setup steps for the environment.
792 <p>
793
794 Setup the environment variables and path for the Micrososft Visual C compiler.
795
796 Typically this can be done by running the VCVARS32.BAT file supplied with
797 Microsoft Visual C++. (contained in the same directory as cl.exe).
798 <p>
799 karl 1.1 For Windows, try the following for an example environment:
800 <blockquote>
801 <pre>REM call the standard Microsoft .bat for VC 6 setup.
802 call 'C:/Program Files/Microsoft Visual Studio/VC98/Bin/Vcvars32.bat'
803 REM Set debug to something if you want compile in debug mode
804 set PEGASUS_DEBUG=true
805 REM set PEGASUS_ROOT to top of source tree
806 set PEGASUS_ROOT=C:/cimom/pegasus
807 REM set PEGASUS_HOME to where you want repository and executables
808 set PEGASUS_HOME=%PEGASUS_ROOT%
809 REM setup the path to the runtime files.
810 set path=%path%;%PEGASUS_HOME%/bin
811 </pre>
812 </blockquote><h1><a name="Installing the Pegasus HTML Test Client">Installing the Pegasus HTML Test Client</a></h1><p>
813 This is a separate test tool that allows Pegasus requests to be initiated from
814 any WEB browser and that uses a WEB browser, CGI scripts and HTML pages for
815 the formatting and connections. It requires a WEB server, etc. The
816 instructions for setting up this environment are maintained in a separate readme in the CGI directory. <h1><a name="Development with Pegasus and Pegasus Tools">Development with Pegasus and Pegasus Tools</a></h1><p>
817 ATTN: This section needs to be completed. It should reference the more
818 complete documentation
819 ATTN: Write about providers? <h1><a name="Commands">Commands</a></h1><p>
820 karl 1.1 The manpages for each of the commands are in rpm/manLinux/man1.Z directory (on
821 CVS) <p>
822 To see simple help for each of the commands, use the "-h" flag. <blockquote><pre>Examples:
823 bin/cimserver –s (Shuts it down)
824 bin/cimserver traceLevel=4 traceComponents=ALL (starts server with config flags)
825 bin/cimprovider –l –s (lists providers and their status)
826 bin/cimprovider –e –m OperatingSystemModule (enables the OperatingSystem provider)
827 bin/cimuser –a –u guest –w ThePassword
828 bin/cimuser –l (lists the users)
829 bin/tomof CIM_Config (extract CIM_Config from repository and present it in MOF type)
830 </pre>
831 </blockquote><h1><a name="Creating SSL certifications">Creating SSL certifications </a></h1><p>
832 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
833 directory. <blockquote><pre>CN="Common Name"
834 EMAIL="test@email.address"
835 HOSTNAME=`uname -n`
836 sed -e "s/$CN/$HOSTNAME/" \
837 -e "s/$EMAIL/root@$HOSTNAME/" $PEGASUS_ROOT/ssl.cnf \
838 > $PEGASUS_HOME/ssl.cnf
839 chmod 644 $PEGASUS_HOME/ssl.cnf
840 chown bin $PEGASUS_HOME/ssl.cnf
841 karl 1.1 chgrp bin $PEGASUS_HOME/ssl.cnf
842
843 /usr/bin/openssl req -x509 -days 365 -newkey rsa:512 \
844 -nodes -config $PEGASUS_HOME/ssl.cnf \
845 -keyout $PEGASUS_HOME/key.pem -out $PEGASUS_HOME/cert.pem
846
847 cat $PEGASUS_HOME/key.pem $PEGASUS_HOME/cert.pem > $PEGASUS_HOME/server.pem
848 rm $PEGASUS_HOME/key.pem $PEGASUS_HOME/cert.pem
849 cp $PEGASUS_HOME/cert.pem $PEGASUS_HOME/client.pem
850 </pre></blockquote><h1><a name="Testing with ICU enabled">Testing with ICU enabled</a></h1><p>
851 ICU (International Components for Unicode) refers to the set of libraries that
852 Pegasus uses to run globalized. For example: these libraries are used to
853 load messages in different languages, format currency and numbers according to
854 a specific locale etc. In order to enable globalization in Pegasus, Pegasus
855 must be built with ICU enabled, ie. the right environment variables must be
856 set prior to running "make". Refer to the GlobalizationHOWTO.htm in the docs
857 directory for details. That said, when users run "make poststarttests"
858 to verify the integrity of a Pegasus download, a series of tests are run that
859
860 require the cimserver to be running. These tests currently depend on specific
861
862 karl 1.1 messages returned from the server. When ICU is enabled, all messages come
863 from the resource bundles and these usually do not match the hardcoded default messages within Pegasus. These hardcoded default messages
864 are what the various test programs expect in order to complete
865 successfully. If the ICU enabled server is started without
866 disabling message loading from the bundles, "make poststartests" will fail.
867 In order to run "make poststarttests" successfully with ICU enabled, an
868 environment variable called PEGASUS_USE_DEFAULT_MESSAGES must exist prior to
869 starting the server. Once this is defined, when the cimserver starts, all
870 messages generated will be the default hardcoded messages. This will enable
871 "make poststarttests" to complete successfully. Once "make poststarttests" is
872 complete, you should stop the cimserver and then undefine PEGASUS_USE_DEFAULT_MESSAGES.
873 If this variable is left defined, Pegasus will not be able to load messages
874 using ICU resource bundles. <h1><a name="Pegasus Documentation">Pegasus Documentation</a></h1><p>
875 The documentation is currently in preparation. Much of Pegasus is
876 documented in the PEGASUS PEPs which are the basis for approval of Pegasus
877 functioanlity, changes, plans, etc. These documents are openly available
878 on the PEGASUS web site. The preliminary documentation
879 is not provided with this release. The current documentation is maintained both as a manual created
880 under the tool DOC++ in the runtime subdirectory manual/html (see doc/devManual
881 to create), as an api document also creatable from the source tree (see doc/apidoc)
882 and as other miscellaneous documentation in the doc directory. Also there is a
883 karl 1.1 set of release notes. Normally the release notes for the current release are
884 available in the root source directory of CVS.<p>
885 Note that the Pegasus WEB site at The Open Group will be the source of most
886 documentation in the future and today is the source of most discussion and
887 design documentation. <h1><a name="Participate!">Participate!</a></h1><p>
888 We are looking for people who want to join the Pegasus work group and
889 contribute to effort of getting this Pegasus off the ground. Please join
890 the mailing list by visiting www.openpegasus.org, and click on Mailing Lists.
891 </p>
892
893 </body>
894
895 </html>
|