README.html

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