pegasus/README.html - annotate

Return to README.html CVS log

Up to [Pegasus] / pegasus

1 dave.sudlik 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 karl 1.6.8.1 <html> 3 <head> 4 <meta http-equiv="Content-Language" content="en-us"> 5 <meta name="GENERATOR" content="Microsoft FrontPage 6.0"> 6 <meta name="ProgId" content="FrontPage.Editor.Document"> 7 <meta http-equiv="Content-Type" 8 content="text/html; charset=windows-1252"> 9 <title>OpenPegasus 2.6 README</title> 10 <link rel="stylesheet" 11 href="http://www.opengroup.org/stylesheets/info1+margins.css"> 12 <style>
13 karl 1.3 <!--
14 karl 1.6 table.MsoNormalTable 15 {mso-style-parent:""; 16 font-size:10.0pt; 17 font-family:"Times New Roman"}
18 karl 1.3 -->
19 karl 1.6.8.1 </style>
20 dave.sudlik 1.1 </head> 21 <body> 22 <hr>
23 karl 1.6 <p><b>Abstract:</b>  Installation, build, 24 and operation
25 dave.sudlik 1.1 information on
26 karl 1.3 the OpenPegasus Version 2.8.0
27 dave.sudlik 1.1 Release. Note that if this readme 28 conflicts with the documentation in the release notes or interface 29 definition documents for a particular release, those documents should 30 be considered authoritative. This is a simplified 31 overview to act as an 32 introduction to OpenPegasus.</p> 33 <hr>
34 karl 1.6 <p align="center"><b><font size="5">OpenPegasus 35 - A Manageability
36 dave.sudlik 1.1 Services Broker for the DMTF CIM/WBEM Standards 37 </font></b></p>
38 karl 1.6 <p align="left"><b>Tagline:</b> OpenPegasus is 39 an object manager for
40 dave.sudlik 1.1 DMTF CIM objects written in C++ 41 and hosted by The Open Group </p> 42 <a href="#Overview">OpenPegasus Overview</a>
43 karl 1.6.8.1 <blockquote style="margin-top: 0pt; margin-bottom: 0pt;"> <a 44 href="#avail_of_peg">Availability</a><br> 45 <a href="#peg_sup_plat">Supported Platforms</a><br> 46 <a href="#peg_dep">Dependencies</a><br> 47 <a href="#cmnd">Commands</a><br> 48 <a href="#docs">Documentation</a><br> 49 <a href="#part">How to Participate</a><br>
50 dave.sudlik 1.1 </blockquote> 51 <a href="#inst_peg">Installing OpenPegasus</a>
52 karl 1.6.8.1 <blockquote style="margin-top: 0pt; margin-bottom: 0pt;"><a 53 href="#download">Download or Checkout</a><br> 54 <a href="#vfy_req_sw">Verify Dependencies</a><br> 55 <a href="#set_envt_var">Set the Environment Variables</a><br> 56 <a href="#bld_peg">Build the Executables</a><br> 57 <a href="#pop_peg_rep">Populate the Repository</a><br> 58 <a href="#reg_prov">Register Providers</a><br> 59 <a href="#note_bld_peg_lnx">Notes
60 dave.sudlik 1.1 about Building on Linux</a><br>
61 karl 1.6.8.1 <a href="#bld_peg_win">Notes about Building
62 dave.sudlik 1.1 on Windows</a><br>
63 karl 1.6.8.1 <blockquote style="margin-top: 0pt; margin-bottom: 0pt;"> 64 <a href="#mu_utility">The MU Utility</a><br> 65 </blockquote> 66 <a href="#note_bld_peg_ssl">Notes about
67 dave.sudlik 1.1 Building with SSL</a><br> 68 </blockquote> 69 <a href="#test">Testing an OpenPegasus installation</a><br>
70 karl 1.6.8.1 <blockquote style="margin-top: 0pt; margin-bottom: 0pt;"> <a 71 href="#test_icu">Testing with ICU enabled</a><br>
72 dave.sudlik 1.1 </blockquote> 73 <hr>
74 karl 1.6 <h1><a name="Overview">OpenPegasus Overview</a> 75 </h1> 76 <div style="margin-left: 40px;"><b>OpenPegasus </b>(also 77 referred to 78 as <b>Pegasus</b>) is an open-source CIM Server for DMTF 79 CIM objects.
80 dave.sudlik 1.1 It is 81 written 82 in C++ and includes the Object manager (CIMOM), a set of defined 83 interfaces, an implementation of the CIM Operations over HTTP 84 operations 85 and their cimxml HTTP encodings, and Interface libraries 86 for both clients and providers. It is maintained 87 to be compliant with 88 the DMTF CIM and WBEM specifications with 89 exceptions 90 noted in the documentation.<br> 91 <br>
92 karl 1.6 <span class="norm"></span>OpenPegasus includes 93 components for: <br>
94 dave.sudlik 1.1 </div>
95 karl 1.3 <blockquote>
96 karl 1.6.8.1 <ol style="margin-left: 40px;"> 97 <li>A DMTF compliant CIM Server that processes CIM
98 karl 1.6 operations, CIM
99 dave.sudlik 1.1 Indications, and 100 includes class and instance repositories and interfaces for creating 101 CIM 102 Providers and CIM Clients.</li>
103 karl 1.6.8.1 <li>Provider interfaces so that providers may be build in
104 karl 1.6 multiple
105 dave.sudlik 1.1 languages (i.e. 106 C++, C, Java).</li>
107 karl 1.6.8.1 <li>A number of CIM Providers.</li> 108 <li>A MOF compiler.</li> 109 <li>A number of CIM Clients to provide usage examples, CIM
110 karl 1.6 Server
111 dave.sudlik 1.1 test functions, 112 and administrative 113 functions.</li>
114 karl 1.6.8.1 <li>More complete information on the exact functions
115 kumpf 1.2 and their functional state is available from the Release Notes
116 karl 1.6.8.1 (pegasus/ReleaseNotes.htm) and the OpenPegasus <a 117 href="http://www.openpegasus.org/page.tpl?CALLER=index.tpl&ggid=799">Feature
118 dave.sudlik 1.1 Status Page</a>.</li>
119 karl 1.6.8.1 </ol>
120 karl 1.3 </blockquote>
121 karl 1.6 <div style="margin-left: 40px;">OpenPegasus is open source 122 and is
123 dave.sudlik 1.1 covered under the MIT open-source 124 license. 125 </div>
126 karl 1.6 <p style="margin-left: 40px;">OpenPegasus is being 127 developed and
128 dave.sudlik 1.1 maintained under the auspices of 129 The 130 Open
131 karl 1.6 Group.  OpenPegasus is maintained under the license defined in 132 the
133 dave.sudlik 1.1 doc
134 karl 1.6.8.1 directory of this release.  The specific file is: <font 135 style="color: rgb(0, 0, 0);">pegasus/doc/license.txt</font>.
136 dave.sudlik 1.1 This licensing is intended to support as 137 wide a 138 distribution as possible with minimal demands on the users. 139 </p>
140 karl 1.6 <p style="margin-left: 40px;">More information on this 141 project, access
142 dave.sudlik 1.1 to the CVS, and
143 karl 1.6.8.1 documentation<span style="color: rgb(255, 0, 0);"><span 144 style="text-decoration: line-through;"></span></span>
145 karl 1.6 is available
146 karl 1.6.8.1 from the Ope<span style="color: rgb(255, 0, 0);"><span 147 style="text-decoration: line-through;"></span></span>nPegasus
148 karl 1.6 web
149 dave.sudlik 1.1 site. 150 </p>
151 karl 1.6 <p style="margin-left: 40px;">    152 <a target="blank" href="http://www.openpegasus.org/">http://www.openpegasus.org</a><br>
153 dave.sudlik 1.1 </p> 154 <p style="margin-left: 40px;">Note 155 that all references in this readme to files in the OpenPegasus source 156 tree are of the form pegasus/..., where "pegasus" is the top-level
157 karl 1.6 directory and also the name of the OpenPegasus module in the Pegasus 158 CVS 159 repository. There are also  other CVS modules for the 160 OpenPegasus Java client (pegasus-JavaCIMClient) 161 and for unsupported components and utilities for Pegasus that may be 162 checked out
163 karl 1.3 separately.  You can use
164 karl 1.6 <a href="http://cvs.opengroup.org/cgi-bin/viewcvs.cgi/">viewCVS</a> 165 to view the
166 karl 1.3 Pegasus CVS tree<br>
167 dave.sudlik 1.1 </p> 168 <h2><a name="avail_of_peg">Availability</a></h2>
169 karl 1.6 <div style="margin-left: 40px;">OpenPegasus is distributed 170 as open
171 dave.sudlik 1.1 source under the MIT open-source 172 license. The distribution is available via CVS, and as snapshot images 173 in 174 tar, zip, and (self-extracting) exe 175 file 176 formats on the OpenPegasus web site.</div> 177 <ol style="color: rgb(0, 0, 0);"> 178 OpenPegasus can be obtained via any of the following:<br>
179 karl 1.6.8.1 <ol> 180 <li>Released tarballs (see <a 181 href="http://www.openpegasus.org/page.tpl?CALLER=page.tpl&ggid=392">ZIP/GZ/EXE
182 dave.sudlik 1.1 link for this release</a>)</li>
183 karl 1.6.8.1 <li>CVS (See <a 184 href="http://www.openpegasus.org/protected/page.tpl?CALLER=index.tpl&ggid=667">CVS
185 dave.sudlik 1.1 code repository</a> for 186 more information)</li>
187 karl 1.6.8.1 <li>Linux RPMs 188 (see <a 189 href="http://www.openpegasus.org/page.tpl?CALLER=page.tpl&ggid=392">RPM
190 dave.sudlik 1.1 link for this release</a>)</li>
191 karl 1.6.8.1 </ol>
192 dave.sudlik 1.1 </ol>
193 karl 1.6.8.1 <p style="margin-left: 40px;"><span class="norm"></span><font 194 style="color: rgb(0, 0, 0);">CVS
195 dave.sudlik 1.1 write accounts are managed by Martin Kirk of The Open Group </font> 196 (<a href="mailto:%28k.m.kirk@opengroup.org">m.kirk@opengroup.org</a>)  197 </p> 198 <h2><a name="peg_sup_plat">Supported Platforms</a></h2>
199 karl 1.6 <p style="margin-left: 40px;">OpenPegasus is regularly 200 tested against a
201 dave.sudlik 1.1 variety of platforms by the
202 karl 1.6 development group.  The results of the nightly tests can be 203 found
204 karl 1.6.8.1 here on our <a 205 href="http://cvs.opengroup.org/cgi-bin/pegasus-build-status.cgi">Nightly 206 Build and Test Status</a> page.  The Release Notes for each 207 release
208 kumpf 1.2 (pegasus/ReleaseNotes.htm) provide additional details
209 karl 1.6.8.1 regarding the platforms, compilers, etc. for the current release.<br>
210 dave.sudlik 1.1 </p> 211 <h2><a name="peg_dep">Dependencies</a></h2> 212 <p style="margin-left: 40px;"> 213 We have worked to minimize the dependence of OpenPegasus on other 214 software 215 packages and tools. Currently OpenPegasus has the following
216 karl 1.6 dependencies. Note that all of the dependencis listed below are 217 required only if selected options are enabled except for GNUMAKE which 218 is the required make tool:
219 dave.sudlik 1.1 </p> 220 <ol style="margin-left: 40px;">
221 karl 1.6.8.1 <li><b>GNUMAKE</b> - To simplify the building of
222 karl 1.6 OpenPegasus across
223 dave.sudlik 1.1 multiple platforms we 224 have standardized on a set of build tools including: GNUMAKE. We are 225 using GNUMAKE 3.79.1 successfully both in Windows and Linux 226 environments. It is available from <a href="http://www.gnu.org">http://www.gnu.org</a>.
227 karl 1.6 The windows version  of GNUMAKE is available on the Pegasus
228 karl 1.6.8.1 web site <a 229 href="http://www.openpegasus.org/pb/protected/index.tpl?CALLER=index.tpl">
230 karl 1.6 tools page</a>.</li>
231 karl 1.6.8.1 <li><b>FLEX</b> and <b>BISON</b> -
232 karl 1.6 These tools were used to develop the MOF 233 compiler and WQL and CQL parsers.  These tools are required <b>ONLY</b> 234 for 235 development of the parsers, not for building OpenPegasus.  236 Bison
237 kumpf 1.2 version 2.3 or later and flex version 2.5.4 or later are required.</li>
238 karl 1.6.8.1 <li><b>Doxygen </b>- The OpenPegasus documentation
239 karl 1.6 is taken from a combination of text files and header files themselves. 240 This documentation is formatted with Doxygen and GAWK.  This 241 is required <b>ONLY</b> if you want to build documentation
242 karl 1.6.8.1 from the source tree.  <span class="norm"></span><font 243 style="color: rgb(0, 0, 0);">These tools are required to
244 karl 1.6 build the
245 dave.sudlik 1.1 interface documentation set.</font> </li>
246 karl 1.6.8.1 <li><b>ICU Internationalization libraries</b> -
247 karl 1.6 These libraries are
248 dave.sudlik 1.1 used as the basis for message catalogs for message 249 internationalization. See the ICU website 250 (<a href="http://icu.sourceforge.net/">http://icu.sourceforge.net</a>) 251 for more information on these
252 karl 1.6 libraries.<span style="color: rgb(255, 0, 0);"> These 253 libraries are used ONLY if you set the requisite environment variable ( 254 PEGASUS_HAS_ICU) to use ICU</span><br>
255 karl 1.6.8.1 </li> 256 <li><b>OpenSSL 257 </b>- If it
258 dave.sudlik 1.1 is intended to use SSL on the
259 karl 1.6.8.1 communication protocol, the OpenSSL libraries are required (<a 260 href="http://www.openssl.org">http://www.openssl.org</a>).</li> 261 <li><span style="font-weight: bold;">OpenSLP</span>
262 karl 1.6 - If you choose
263 dave.sudlik 1.1 to use 264 OpenSLP as your choice of SLP implementations, then it will need to be 265 installed and available to OpenPegasus. Refer to the
266 karl 1.6 PEGASUS_USE_OPENSLP and PEGASUS_OPENSLP_HOME build variables in the
267 karl 1.6.8.1 doc/BuildAndReleaseOptions.html file, and the OpenSLP web site (<a 268 href="http://www.openslp.org">http://www.openslp.org</a>).</li> 269 <li><span style="font-weight: bold;">zlib 270 </span>- If you choose to
271 dave.sudlik 1.1 enable the compressed repository feature with the 272 PEGASUS_ENABLE_COMPRESSED_REPOSITORY build variable, you will need to 273 install the gzip (GNU zip) compression utility. Refer to 274 readme.compressed_repository in OpenPegasus source tree, and the gzip
275 karl 1.6.8.1 web site (<a style="color: rgb(204, 51, 204);" 276 href="http://www.gzip.org">http://www.gzip.org</a>).</li> 277 <li><span style="font-weight: bold;">sqlite</span>
278 karl 1.6 - If you choose to enable the use of sqlite for the repository, refer 279 to the doc/BuildAndReleaseOptions.html file for the defintion of the 280 build variables and the sqlite implementation which may be obtained
281 karl 1.6.8.1 either as part of a standard distribution or from <a 282 href="http://www.sqlite.org">http://www.sqlite.org</a>.</li>
283 dave.sudlik 1.1 </ol> 284 <p style="margin-left: 40px;"><span style="font-weight: bold;">NOTE</span>: 285 A set of the required 286 tools for building on the Windows platform is available on the
287 karl 1.6.8.1 OpenPegasus <a 288 href="http://www.openpegasus.org/pb/index.tpl?CALLER=index.tpl">Tools</a>
289 dave.sudlik 1.1 web page.<br> 290 </p> 291 <h2><a name="cmnd">Commands</a></h2> 292 <p style="margin-left: 40px;">
293 karl 1.6 Pegasus includes the server which can be controlled from the command 294 line and a
295 karl 1.3 set of clients that provide adminstrative functions</p> 296 <p style="margin-left: 40px;">
297 dave.sudlik 1.1 The manpages for each of the commands are in the pegasus/rpm/manLinux/ 298 directory (from CVS). </p>
299 karl 1.6 <p style="margin-left: 40px;">To see simple help for each 300 command,
301 dave.sudlik 1.1 invoke it with the "--help" option.<br> 302 </p>
303 karl 1.6.8.1 <div style="margin-left: 40px;"><span style="font-weight: bold;">Some 304 of
305 dave.sudlik 1.1 the basic commands:</span> 306 <br> 307 </div> 308 <ul>
309 karl 1.6.8.1 <ul> 310 <li><span style="font-family: monospace;">cimserve</span>r
311 karl 1.6 (Start the server
312 dave.sudlik 1.1 cimserver)</li>
313 karl 1.6.8.1 <li><span style="font-family: monospace;">cimserver
314 karl 1.6 -s</span>  (Shuts down the cimserver)</li>
315 karl 1.6.8.1 <li><span style="font-family: monospace;">cimserver
316 karl 1.6 traceLevel=4 traceComponents=ALL</span>  317 (Starts server
318 dave.sudlik 1.1 with 319 config flags)</li>
320 karl 1.6.8.1 </ul> 321 <ul> 322 <li><span style="font-family: monospace;">cimprovider
323 karl 1.6 -l -s</span>  (Lists providers and their 324 status)</li>
325 karl 1.6.8.1 <li><span style="font-family: monospace;">cimprovider
326 karl 1.6 -e -m OperatingSystemModule</span>  327 (Enables the
328 dave.sudlik 1.1 OperatingSystem provider)</li>
329 karl 1.6.8.1 <li><span style="font-family: monospace;">cimuser
330 karl 1.6 -a -u guest _w <ThePassword></span> (Adds 331 the user <span style="font-style: italic;">guest</span> 332 with specified password)<br>
333 karl 1.6.8.1 </li> 334 <li><span style="font-family: monospace;">cimuser
335 karl 1.6 -l</span>  (Lists the users )</li>
336 karl 1.6.8.1 <li><span style="font-family: monospace;">cimconfig
337 karl 1.6 -l -c</span> (Lists the 338 current config options and their current values)<br>
339 karl 1.6.8.1 </li> 340 </ul>
341 dave.sudlik 1.1 </ul>
342 karl 1.3 <div style="margin-left: 40px;"><span style="font-weight: bold;">NOTES</span>:
343 dave.sudlik 1.1 <br> 344 </div>
345 karl 1.3 <blockquote>
346 karl 1.6.8.1 <ol style="margin-left: 40px;"> 347 <li>Refer to the admin guide in
348 karl 1.6 pegasus/doc/Admin_Guide_Release.pdf
349 dave.sudlik 1.1 for 350 more information about administering the OpenPegasus CIM Server.</li>
351 karl 1.6.8.1 <li>There are differences between Windows and other
352 dave.sudlik 1.1 platforms in
353 karl 1.6 starting the CIMserver as a daemon/service. Whereas most supported
354 dave.sudlik 1.1 platforms use 355 the OpenPegasus <span style="font-weight: bold;">daemon</span> 356 configuration option to start the CIM Server as a daemon, on 357 Windows it 358 must be specifically installed as a service (ex. cimserver -install) 359 and then 360 started as a service (cimserver -start). The cimserver --help option 361 explains the 362 exact format of the start and stop options.</li>
363 karl 1.6.8.1 <li>The cimuser command is used to manage OpenPegasus users
364 karl 1.6 only when 365 the CIM Server is compiled without the PEGASUS_PAM_AUTHENTICATION
366 karl 1.6.8.1 environment variable defined. See <a 367 href="http://www.openpegasus.org/pp/uploads/40/16781/PEP308_RecommendedReleaseOptions.htm">
368 karl 1.6 PEP 308</a> for more information on these configuration options.<br>
369 karl 1.6.8.1 </li> 370 </ol>
371 karl 1.3 </blockquote>
372 karl 1.6 <a name="docs">Documentation</a> 373 <p style="margin-left: 40px;">Much
374 dave.sudlik 1.1 of 375 OpenPegasus
376 karl 1.6.8.1 is documented in the <a 377 href="http://www.openpegasus.org/pp/index.tpl?CALLER=index.tpl">Pegasus
378 karl 1.6 Enhancement Process (PEPs)</a> which are the basis for approval 379 of 380 OpenPegasus functionality, changes, plans, etc.  The approved 381 PEPs
382 karl 1.6.8.1 are publicly available on the OpenPegasus web site.<span 383 style="color: rgb(255, 0, 0);"><br>
384 dave.sudlik 1.1 </span></p> 385 <p style="margin-left: 40px;">Other 386 documentation available 387 is an api document (creatable 388 from the 389 source tree, see pegasus/doc/apidoc) and other miscellaneous 390 documentation
391 karl 1.6.8.1 in the CVS doc directory and the pegasus CVS root as readme files. 392 Also, there is a set of Release Notes for each
393 karl 1.3 release in the OpenPegasus root
394 karl 1.6.8.1 source directory of CVS and as a Pegasus PEP.</p>
395 dave.sudlik 1.1 <h2><a name="part">How to Participate</a></h2>
396 karl 1.6 <p style="margin-left: 40px;"><font style="color: rgb(0, 0, 0);">Contributors
397 dave.sudlik 1.1 are welcome to participate in the OpenPegasus development effort. Join
398 karl 1.6.8.1 the mailing list by going to the <a 399 href="http://www.openpegasus.org/mailinglists.tpl?CALLER=index.tpl">Mailing
400 dave.sudlik 1.1 Lists</a> web page from the OpenPegasus site.</font></p> 401 <h1> 402 <a name="inst_peg">Installing OpenPegasus</a> </h1> 403 <h2><a name="download"></a>Download or Checkout</h2> 404 <p style="margin-left: 40px;">Refer to the <a href="#avail_of_peg">Availability</a> 405 section for instructions on obtaining source code.<br> 406 </p>
407 karl 1.6 <p style="margin-left: 40px;">If you want to install 408 pre-built Pegasus
409 karl 1.6.8.1 executables instead of building from source code, then refer to the <a 410 href="http://www.openpegasus.org/pr/">RPM installation
411 karl 1.6 instructions</a>.<br> 412 </p> 413 <h2><strong><strong><a name="vfy_req_sw"></a>Verify
414 karl 1.6.8.1 Dependencies</strong></strong><strong><strong><span 415 style="font-weight: normal;"></span></strong></strong></h2> 416 <p style="margin-left: 40px;"><strong><strong><span 417 style="font-weight: normal;">Be</span></strong></strong>fore
418 dave.sudlik 1.1 you build, install, or run OpenPegasus, be sure you have the proper set 419 of software 420 it depends on.  Refer to the section <a href="#peg_dep">Dependencies</a> 421 for 422 the complete list.<br> 423 </p> 424 <strong></strong>
425 karl 1.6 <h2><a name="set_envt_var"><strong>Set the 426 Environment
427 dave.sudlik 1.1 Variables</strong></a></h2>
428 karl 1.6 <p style="margin-left: 40px;">Before building, installing, 429 or running
430 dave.sudlik 1.1 OpenPegasus, some environment variables may
431 karl 1.6 have to be defined or updated.  See PEP 292 for the full list 432 of
433 dave.sudlik 1.1 environment variables and configuration options for OpenPegasus. The 434 minimum set is:<br> 435 </p> 436 <ul>
437 karl 1.6.8.1 <ul> 438 <li>PEGASUS_ROOT -- The directory
439 karl 1.3 containing the OpenPegasus root directory from CVS.</li>
440 karl 1.6.8.1 <li>PEGASUS_HOME -- The directory
441 dave.sudlik 1.1 that will contain all output from building and running OpenPegasus, it 442 can be the same as PEGASUS_ROOT if desired.</li>
443 karl 1.6.8.1 <li>PEGASUS_PLATFORM -- The 444 platform on which OpenPegasus is being built.</li> 445 </ul> 446 </ul> 447 <div style="margin-left: 40px;">There are a significant number of 448 environment variables that control the compile and test of features in 449 the OpenPegasus package in addition to the 3 variables described above. 450 These variables are documented in the Pegasus documentation in CVS (see 451 the pegasus/doc directory).</div>
452 dave.sudlik 1.1 <h2><a name="bld_peg"></a>Build the Executables<br> 453 </h2> 454 <div style="margin-left: 40px;">OpenPegasus
455 karl 1.6 is compiled and linked using a make structure that recurses through 456 the  OpenPegasus source tree.<br>
457 karl 1.6.8.1 <font><font color="RED"><span 458 style="color: rgb(0, 0, 0); font-weight: bold;"><br>
459 dave.sudlik 1.1 Makefile commands 460 </span></font></font><br> 461 <br>
462 karl 1.6 OpenPegasus
463 dave.sudlik 1.1 includes several Makefiles that enable 464 you to quickly build or 465 refresh files for the server, clients, providers, test cases, and 466 repository. To use these Makefiles, type "make" followed by one of the 467 supplied targets.  <br> 468 <br> 469 For more information on the 470 available make targets, enter "make usage" from the PEGASUS_ROOT 471 directory. A recommended minimum set 472 to know are: 473 <br> 474 <ul>
475 karl 1.6.8.1 <li>usage -- Explains the
476 dave.sudlik 1.1 available make targets in some detail.</li>
477 karl 1.6.8.1 <li>new -- Clean out all
478 dave.sudlik 1.1 objects, libs, executables, and the repository.</li>
479 karl 1.6.8.1 <li>build -- Builds
480 dave.sudlik 1.1 dependencies, compiles, links, and installs the server. After this 481 OpenPegasus is ready to run.</li>
482 karl 1.6.8.1 <li>alltests - Builds the
483 dave.sudlik 1.1 repository entries and other resources required by the tests, and then 484 executes all automated tests.</li>
485 karl 1.6.8.1 <li>world - Builds the complete environment and runs the test suite.</li>
486 dave.sudlik 1.1 </ul>
487 karl 1.6 For a comprehensive
488 dave.sudlik 1.1 list of  the
489 karl 1.6.8.1 make targets, refer to <big><span 490 style="font-family: Courier New,Courier,monospace;">pegasus/Makefile</span></big>
491 karl 1.6 at the top of the OpenPegasus source directory.<br>
492 dave.sudlik 1.1 </div> 493 <ul> 494 </ul>
495 karl 1.6 <h2><a name="pop_peg_rep">Populate the Repository</a> 496 </h2>
497 dave.sudlik 1.1 <p style="margin-left: 40px;"> 498 Before using OpenPegasus you must populate the repository. Typically, 499 this
500 karl 1.6 is done during the build process by the 'make repository' target. 501 However,
502 dave.sudlik 1.1 you 503 can also compile MOF (Managed Object Format) code manually with the 504 cimmof compiler.<br> 505 </p>
506 karl 1.6 <p style="margin-left: 40px;">The 'make repository' target
507 karl 1.6.8.1 in the makefile <big><span 508 style="font-family: Courier New,Courier,monospace;">pegasus/Makefile</span></big>
509 karl 1.6 performs several functions including:
510 dave.sudlik 1.1 </p> 511 <ul>
512 karl 1.6.8.1 <li><span style="color: rgb(0, 0, 0);">Removes
513 karl 1.6 the existing
514 dave.sudlik 1.1 repository (if one exists).</span><br>
515 karl 1.6.8.1 </li> 516 <li>Generates the default
517 karl 1.3 CIM Schema (defined in pegasus/mak/config.mak)
518 dave.sudlik 1.1 in the repository (skeleton of CIM
519 karl 1.6 objects).  Refer to PEGASUS_CIM_SCHEMA environment 520 variable  in  Pegasus PEP 308  to 521 set  alternate schema versions.<br>
522 karl 1.6.8.1 </li> 523 <li>Loads
524 dave.sudlik 1.1 schema for CIM Server functions (shutdown, add users, etc) and 525 CIM indications 526 (SNMP, Events, Alert, Threshold, etc) 527 internal to Pegasus. </li>
528 karl 1.6.8.1 <li>Registers included CIM Providers (libOSProvider.so, 529 libDNSProvider.so, … ) in OpenPegasus (which are located in
530 dave.sudlik 1.1 src/Providers) <br>
531 karl 1.6.8.1 </li>
532 dave.sudlik 1.1 </ul> 533 <h2><a name="reg_prov">Register 534 Providers</a></h2>
535 karl 1.6 <p style="margin-left: 40px;">OpenPegasus registers 536 Providers using a
537 dave.sudlik 1.1 set of provider registration classes
538 karl 1.6.8.1 encoded in MOF. This classes are proprietary to OpenPegasus 539 today.  </p>
540 dave.sudlik 1.1 <p style="margin-left: 40px;">Registration 541 is performed by creating instances of the 542 registration classes that represent the provider module, providers, 543 capabilities, etc. to be 544 registered.  The easiest way to create a new 545 registration today is to copy from one of the existing registration
546 karl 1.6.8.1 MOFs.  See the <big><span 547 style="font-family: Courier New,Courier,monospace;">pegasus/src/Providers/sample/Load</span></big>
548 karl 1.6 directory for examples of
549 dave.sudlik 1.1 several registration instance implementations that do work with 550 OpenPegasus 551 today.</p>
552 karl 1.6.8.1 <p style="margin-left: 40px;">Registration may be performed by creating 553 compiling the registration mof with either the on-line or off-line 554 Pegasus mof compiler.  It is recommended that providers be 555 registered with the on-line compiler because this allows pegasus to 556 validate the registration information.</p>
557 dave.sudlik 1.1 <h2><a name="note_bld_peg_lnx">Notes about 558 Building on Linux </a></h2> 559 <p style="margin-left: 40px;"> 560 To build OpenPegasus on Linux, ensure that you you have the necessary 561 environment
562 karl 1.6 variables set (eg. PEGASUS_HOME, PEGASUS_ROOT, 563 PEGASUS_PLATFORM).
564 dave.sudlik 1.1 For
565 karl 1.3 32 bit Linux, the definition of PEGASUS_PLATFORM is normally
566 karl 1.6 LINUX_IX86_GNU.   For 64 bit IX86  Linux the 567 definition 568 of
569 karl 1.3 PEGASUS_PLATFORM is normally LINUX_IX86_64_GNU.  Use the g++
570 karl 1.6 compiler to compile and link the executables. All of the supported 571 platform
572 karl 1.6.8.1 definitions are defined in <big><span 573 style="font-family: Courier New,Courier,monospace;">pegasus/mak</span></big>
574 karl 1.6 as  make files with the 575 definition:</p>
576 karl 1.6.8.1 <p style="margin-left: 40px;">    <span 577 style="font-family: monospace;">
578 karl 1.6 platform_<operatingSystem>_<architecture>_<compiler></span></p> 579 <p style="margin-left: 40px;">The 580 <operatingSystem>_<architecture>_<compiler> 581 component is what forms the PEGASUS_PLATFORM environment variable so 582 that the
583 karl 1.3 appropriate platform make file can be found during the build process.<br>
584 dave.sudlik 1.1 </p> 585 <h2><a name="bld_peg_win">Notes 586 about Building on Windows </a></h2> 587 <p style="margin-left: 40px;">
588 karl 1.6 Use of Windows 2000 SP3 or later is recommended.  OpenPegasus 589 is
590 karl 1.6.8.1 regularly tested on mulitple windows platforms.</p> 591 <p style="margin-left: 40px;">We build OpenPegasus
592 karl 1.6 on Windows
593 dave.sudlik 1.1 using a set of Makefiles 594 contained 595 in the source distribution, the Microsoft compilers (DevStudio 5.x is 596 not supported, Visual Studio 6.0 (SP5) or later is supported) and the 597 GNUMAKE
598 karl 1.6.8.1 make utility.  Note that you MUST have the OpenPegasus <a 599 href="#mu_utility">mu.exe </a>utility compiled and
600 karl 1.6 available
601 karl 1.6.8.1 before trying to compile OpenPegasus on the normal windows platform 602 (This utility allows use of unix command line semantics for certain 603 operations in windows).
604 dave.sudlik 1.1 The 605 following is the basic setup steps for the environment. 606 </p>
607 karl 1.6 <p style="margin-left: 40px;">Setup the environment 608 variables and path
609 dave.sudlik 1.1 for the Micrososft Visual C 610 compiler. 611 Typically this can be done by running the VCVARS32.BAT file supplied 612 with Microsoft Visual C++. (contained in the same directory as cl.exe). 613 </p>
614 karl 1.6 <p style="margin-left: 40px;">For Windows, try the 615 following for an
616 dave.sudlik 1.1 example environment: </p> 617 <blockquote>
618 karl 1.6.8.1 <pre style="margin-left: 40px;"><span style="font-family: monospace;">REM call the standard Microsoft .bat for VC 6 setup. </span><br 619 style="font-family: monospace;"><span style="font-family: monospace;">call 'C:/Program Files\Microsoft Visual Studio\VC98\Bin\Vcvars32.bat' </span><br 620 style="font-family: monospace;"><span style="font-family: monospace;">REM Set debug to something if you want to compile in debug mode </span><br 621 style="font-family: monospace;"><span style="font-family: monospace;">set PEGASUS_DEBUG=true </span><br 622 style="font-family: monospace;"><span style="font-family: monospace;">REM set PEGASUS_ROOT to top of source tree </span><br 623 style="font-family: monospace;"><span style="font-family: monospace;">set PEGASUS_ROOT=C:/cimom/pegasus </span><br 624 style="font-family: monospace;"><span style="font-family: monospace;">REM (Note: </span><span 625 style="font-family: monospace;" class="norm">The '/' characters are intentional and required by the OpenPegasus build system). <br>REM Also the disk designator (C:) is required for at least some newer versions of the Microsoft<br>REM  compilers to avoid confusion between options and paths<br></span><span 626 style="font-family: monospace;">REM set PEGASUS_HOME to where you want repository and executables, it can be the same as PEGASUS_ROOT</span><br 627 style="font-family: monospace;"><span style="font-family: monospace;">set PEGASUS_HOME=%PEGASUS_ROOT% </span><br 628 style="font-family: monospace;"><span style="font-family: monospace;">REM set PEGASUS_PLATFORM for Windows</span><br 629 style="color: rgb(255, 0, 0); font-family: monospace;"><span 630 style="font-family: monospace;">set PEGASUS_PLATFORM=WIN32_IX86_MSVC</span><br 631 style="font-family: monospace;"><span style="font-family: monospace;">REM setup the path to the runtime files. </span><br 632 style="font-family: monospace;"><span style="font-family: monospace;">set path=%path%;%PEGASUS_HOME%\bin </span><br></pre>
633 dave.sudlik 1.1 </blockquote> 634 <h3> 635 <a name="mu_utility">The MU Utility </a></h3> 636 <p style="margin-left: 40px;"> 637 In order to provide a consistent build structure across multiple 638 platforms, we 639 developed a utility to provide a consistent set of functions across 640 these platforms. The MU utility is a simple utility that 641 contains 642 many 643 commands. For example: 644 </p> 645 <p style="margin-left: 40px;"><font face="Courier New">
646 karl 1.6 </font><span style="font-family: monospace;">C:\> 647 mu rm myfile.cpp yourfile.cpp</span> </p> 648 <p style="margin-left: 40px;">You may type "mu" to get a 649 list of valid
650 dave.sudlik 1.1 commands. Here are some 651 of them: 652 </p> 653 <p style="margin-left: 40px;">    654 rm, rmdirhier, mkdirhier, echo, touch, pwd, copy, move, compare depend 655 </p>
656 karl 1.6 <p style="margin-left: 40px;">The MU utility supports 657 globing
658 dave.sudlik 1.1 (expansion of wildcards) so 659 you can do things like this: 660 </p>
661 karl 1.6.8.1 <p style="margin-left: 40px;"><font face="Courier New">   </font><span 662 style="font-family: monospace;">
663 karl 1.6 C:\> mu rm .obj .exe</span> </p> 664 <p style="margin-left: 40px;">MU is required to build 665 under the Windows
666 dave.sudlik 1.1 environment. MU is 667 available as part 668 of the distribution of OpenPegasus.<br> 669 </p>
670 karl 1.6.8.1 <div style="margin-left: 40px;"><span style="font-weight: bold;">NOTE:</span> 671 The binary for
672 karl 1.6 MU.EXE is not
673 dave.sudlik 1.1 distributed in the OpenPegasus bin 674 directory. 675 You must build it separately. MU source code is part of the 676 distribution 677 in the directory src/utils/MU with its own make file. You must compile 678 MU 679 before you initiate the OpenPegasus make. A copy of the binary is made
680 karl 1.6.8.1 available as a zip file on the OpenPegasus <a 681 href="http://www.openpegasus.org/pb/index.tpl?CALLER=index.tpl">Tools</a>
682 dave.sudlik 1.1 web page.<br> 683 </div> 684 <h2><a name="note_bld_peg_ssl">Notes about 685 Building with SSL 686 </a></h2> 687 <p style="margin-left: 40px;"> 688 To build with SSL you need the OpenSSL libraries and header files. They 689 are NOT distributed with OpenPegasus. Make sure you have them in a 690 standard 691 directory so OpenPegasus can find them. If that's not 692 the case, set the environment variable OPENSSL_HOME= to point where 693 your OpenSSL
694 kumpf 1.2 installation is (refer to PEP 292
695 dave.sudlik 1.1 for more details on build variables).<br> 696 </p> 697 <p style="margin-left: 40px;">You
698 karl 1.6 must also have the PEGASUS_HAS_SSL environment variable defined. Then 699 when you
700 dave.sudlik 1.1 build 701 OpenPegasus, it 702 will include the SSL support. 703 </p>
704 karl 1.6 <div style="margin-left: 40px;">Refer to the OpenPegasus 705 SSL Guide
706 dave.sudlik 1.1 (found in doc/PegasusSSLGuidelines.htm) 707 for details on 708 using OpenPegasus with SSL, 709 creating SSL certificates, etc.<br> 710 </div> 711 <h1> 712 <a name="test">Testing an OpenPegasus Installation</a></h1> 713 <p style="margin-left: 40px;"> 714 OpenPegasus includes an extensive set of test facilities as part of the 715 CVS 716 environment, including: 717 </p>
718 karl 1.6 <div style="margin-left: 40px;">
719 dave.sudlik 1.1 <ul>
720 karl 1.6.8.1 <li><b>Test Clients</b> - There are several
721 karl 1.6 clients that have been
722 dave.sudlik 1.1 built specifically to test OpenPegasus, or parts of OpenPegasus, 723 including 724 TestClient, Client, cimcli, ipinfo, 725 osinfo, wbemexec, 726 etc. See the 727 src/Clients directory for more information. These programs require a 728 running CIM Server with a 729 complete repository.  Note that some of 730 these tests use classes and instances that are only installed with the 731 "make testrepository" target including: test namespaces, extra 732 classes and instances in those namespaces, and additional sample and
733 karl 1.6 test providers.</li> 734 </ul> 735 </div> 736 <div style="margin-left: 40px;"> 737 <ul>
738 karl 1.6.8.1 <li><b>Sample and Test Providers</b> -
739 karl 1.6 Test providers exist
740 dave.sudlik 1.1 for 741 the major provider types in the src/Providers/sample
742 karl 1.6 and src/Providers/TestProviders directories.</li> 743 </ul> 744 </div> 745 <ul>
746 karl 1.6.8.1 <ul> 747 </ul>
748 karl 1.6 </ul> 749 <div style="margin-left: 40px;"> 750 <ul>
751 karl 1.6.8.1 <li><b>Unit Tests</b> - Most OpenPegasus
752 karl 1.6 functions include unit
753 dave.sudlik 1.1 tests 754 for 755 the functions.  These are normally executed with the "make 756 unittests" 757 top-level target, or "make tests" 758 which can be executed at many different levels of the source 759 tree.  Usually the unit test functions can be found 760 in test 761 directories immediately below their corresponding source code 762 (i.e  Common/tests contains the unit test 763 functions for the Common 764 directory). Unit tests are executed with the CIM Server shutdown and 765 normally do not require the existence of class definitions in the
766 karl 1.6 repository.</li> 767 </ul> 768 </div> 769 <ul style="margin-left: 40px;">
770 karl 1.6.8.1 <li><b>End-to-end Test Suite</b> - the directory
771 karl 1.6 "test" contains
772 dave.sudlik 1.1 a
773 karl 1.6 set of operation 774 tests that cover the major CIM Operations.  See
775 dave.sudlik 1.1 TestMakefile in the PEGASUS_ROOT directory to execute
776 karl 1.6 these tests.  This set of tests executes an extensive set of 777 fixed
778 dave.sudlik 1.1 tests and compares the results against predefined results.</li> 779 </ul>
780 karl 1.6 <p>          781 Once OpenPegasus is 782 successfully built, the  tests can be executed through the 783 root Makefile
784 karl 1.3 with targets such as:</p> 785 <blockquote>
786 karl 1.6.8.1 <ul> 787 </ul> 788 <ul> 789 <li><b>make unittests </b>- Execute the unit
790 karl 1.6 tests. These do not depend on having a running server or repository 791 installed.  They test components of the OpenPegasus code. 792 These tests run to completion if successful but normally stop on the 793 first error found by a test program.</li>
794 karl 1.6.8.1 <ul> 795 </ul> 796 </ul>
797 karl 1.6 </blockquote> 798 <blockquote>
799 karl 1.6.8.1 <ul> 800 <li><b>make servertests</b> - Executes the
801 karl 1.6 OpenPegasus end-to-end test suite against a running OpenPegasus server 802 starting and stopping the server as required to modify configuration 803 parameters. The repository must be installed for these tests to execute 804 and they are tested against the default repository as part of regular 805 OpenPegasus development and release testing. These tests will run to 806 successful completion if there are not errors detected but will 807 normally stop on the first error.  There is a subset of these 808 tests that can be run in an environment that does not have root 809 privileges but root privileges are required to run the complete suite.</li>
810 karl 1.6.8.1 </ul>
811 karl 1.3 </blockquote>
812 karl 1.6 <ul> 813 </ul> 814 <ul style="margin-left: 40px;">
815 karl 1.6.8.1 <li><b>make alltests</b> - execute both the
816 karl 1.6 unit and end-to-end tests.</li> 817 </ul>
818 dave.sudlik 1.1 <h2><a name="test_icu">Testing with ICU enabled</a></h2>
819 karl 1.6 <p style="margin-left: 40px;">ICU (International 820 Components for
821 dave.sudlik 1.1 Unicode) refers to the set of 822 libraries that OpenPegasus uses to run with globalization support. For 823 example, these 824 libraries are used 825 to 826 load messages in different languages, format currency and numbers 827 according to 828 a specific locale etc. In order to enable globalization, OpenPegasus 829 must be built with ICU enabled, ie. the right environment variables 830 must be 831 set prior to running "make". Refer to the GlobalizationHOWTO.htm in the 832 pegasus/docs 833 directory for details.<br> 834 </p>
835 karl 1.6 <p style="margin-left: 40px;">When users run "make 836 servertests"
837 dave.sudlik 1.1 to verify the integrity of an OpenPegasus download, a series of tests 838 are 839 run that 840 require the CIM Server to be running. These tests currently depend on 841 specific 842 messages returned from the CIM Server. When ICU is enabled, all 843 messages 844 come from the resource bundles and these usually do not match the 845 hardcoded default messages within OpenPegasus. These hardcoded default 846 messages are what the various test programs expect in order to complete 847 successfully. If the ICU-enabled CIM Server is started without 848 disabling message loading from the bundles, "make servertests" 849 will 850 fail. 851 In order to run "make servertests" 852 successfully with ICU enabled, an 853 environment variable called PEGASUS_USE_DEFAULT_MESSAGES must be 854 defined 855 prior to 856 starting OpenPegasus. Once 857 this is defined, when OpenPegasus starts, 858 dave.sudlik 1.1 all 859 messages generated will be the default hardcoded messages. This will 860 enable 861 "make servertests" 862 to complete successfully. Once "make 863 servertests" 864 is 865 complete, you should stop OpenPegasus and 866 then undefine 867 PEGASUS_USE_DEFAULT_MESSAGES. If this variable is left defined, 868 OpenPegasus 869 will not be able to load messages 870 using ICU resource bundles.<br> 871 </p> 872 <p style="margin-left: 40px;">When 873 running the "make unittests" 874 command with ICU enabled, the PEGASUS_MSG_HOME 875 environment variable must be set to the home directory where the ICU 876 resource bundles are built. By default the resource bundles are built 877 into directories below PEGASUS_HOME/msg, so that should be the setting 878 for PEGASUS_MSG_HOME.<font style="color: rgb(0, 0, 0);"><br> 879 dave.sudlik 1.1 </font></p> 880 <hr>
881 karl 1.6 <p>Licensed to The Open Group (TOG) under one or more contributor 882 license 883 agreements. Refer to the OpenPegasusNOTICE.txt file distributed with
884 martin 1.5 this work for additional information regarding copyright ownership. 885 Each contributor licenses this file to you under the OpenPegasus Open 886 Source License; you may not use this file except in compliance with the 887 License.</p>
888 karl 1.6 <p>Permission is hereby granted, free of charge, to any person 889 obtaining a 890 copy of this software and associated documentation files (the 891 "Software"), 892 to deal in the Software without restriction, including without 893 limitation 894 the rights to use, copy, modify, merge, publish, distribute, 895 sublicense,
896 martin 1.5 and/or sell copies of the Software, and to permit persons to whom the 897 Software is furnished to do so, subject to the following conditions:</p>
898 karl 1.6 <p>The above copyright notice and this permission notice shall be 899 included
900 martin 1.5 in all copies or substantial portions of the Software.</p>
901 karl 1.6 <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY 902 KIND, EXPRESS
903 martin 1.5 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 904 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 905 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 906 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 907 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 908 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
909 dave.sudlik 1.1 <hr>
910 karl 1.6.8.1 </body> 911 </html>

No CVS admin address has been configured