Contemporary Memo

Building and Installing the WMI Mapper (Windows Only)

## Building the WMI Mapper

### Install Tools and SDKs

#### Visual C++ 6.0 SP5

Pegasus and the WMI Mapper have been built successfully using Visual C++ 6.0, SP5. Other environments (e.g., Visual Studio.NET) may be possible, but are not covered here.

1. Install Visual C++ 6.0

2. Install Visual Studio 6.0 Service Pack 5

3. Add the path to vcvars32.bat (usually “C:\Program Files\Microsoft Visual Studio\VC98\Bin”) to the system PATH

#### Microsoft Platform SDK

Latest version from Microsoft (free download):

http://www.microsoft.com/msdownload/platformsdk/sdkupdate/

1. Select the Downloads|Install menu item

2. Select the following SDK's, as a minimum:

q Core SDK

q WMI SDK

3. Click Install...

4. Add a new environment variable: MSSdk (Control Panel|System|Advanced|Environment Variables), set to where you installed the platform SDK ("C:\Program Files\Microsoft SDK", by default).

5. Add the SDK bin directory (%MSSdk%\bin) to the system PATH environment variable.

#### GNU Make

In order to build using the Pegasus Makefiles, The GNU make utility (make.exe or gnumake.exe) must be available in the PATH (nmake.exe, which comes with Visual C++ will not work!). Information on how to obtain and compile gnumake for Windows can be found here:

http://www.gnu.org/software/make/make.html

#### mu.exe

mu.exe provides platform independent file operations for the Pegasus build environment, and must be available in the PATH for use by the Pegasus Makefiles. Mu.exe may be built from the Pegasus source tree, as follows:

§ set PEGASUS_PLATFORM= WIN32_IX86_MSVC

§ set PEGASUS_MU_BIN_DIR=C:\MU [where you want mu.exe to go – directory must exist]

§ cd %PEGASUS_ROOT%\src\utils\mu

§ make

mu.exe can then be found in %PEGASUS_MU_BIN_DIR%.

Add the directory used for PEGASUS_MU_BIN_DIR to the PATH, so that mu.exe will be found while building Pegasus.

### Configure the Environment

Open a Command Prompt window and run the following commands to configure the environment for building the WMI Mapper. Alternatively, these commands may be put into a batch file.

NOTE: The batch file Pegasus/src/WMIMapper/mkmapper.bat covers most, but not all of the following steps (PEGASUS_ROOT, PEGASUS_HOME, and OPENSSL_HOME must be set before calling mkmapper.bat):

#### Environment Variables

Prior to building the WMI Mapper, set the following environment variables (modify the directories appropriately for your environment).

§ set PEGASUS_HOME=C:\WMIMapper [where you want the output/binaries to go]

§ set PEGASUS_ROOT=C:\Pegasus [root of the Pegasus source tree]

§ set PEGASUS_PLATFORM=WIN32_IX86_MSVC

§ set PEGASUS_DEBUG=1 [Set for debug build only, otherwise “set PEGASUS_DEBUG=” to un-set]

§ set PEGASUS_HAS_SSL=1 [Set to build with SSL support, otherwise “set PEGASUS_HAS_SSL=” to un-set]

§ set OPENSSL_HOME=C:\OpenSSL [root directory of the OpenSSL libraries/sdk. Only needed if PEGASUS_HAS_SSL=1]

§ set PEGASUS_WMIMAPPER=1 [must be set when building BOTH the Pegasus and WMI Mapper files]

#### Build Environment Setup

Setup the Visual C++ environment:

1. call vcvars32.bat

Setup the MS Platform SDK environment (see setenv.bat for additional options):

2. call setenv.bat /2000 /DEBUG

## Build Commands

#### Basic Build Steps

1. First build Pegasus:

§ cd %PEGASUS_ROOT%

§ make rebuild [to clean & rebuild all files, simply run “make” to build changes only]

2. Next, build the WMI Mapper components:

§ cd %PEGASUS_ROOT%\src\WMIMapper

§ make mapper

This will copy certain files from the Pegasus source that are also used to build the WMI Mapper, then will build the Mapper components.

NOTE: When building, all files are output to the following directories:

§ %PEGASUS_HOME%\bin [exe and .dll files]

§ %PEGASUS_HOME%\lib [.lib files]

§ %PEGASUS_HOME%\obj [.obj and other intermediate files]

## WMI Mapper Components

The WMI Mapper has three components. Additionally, it uses several Pegasus libraries. Following is a brief description of the components.

1. WMIServer.exe is the executable. It may be run either as an NT service or a console application. After checking command-line options, it creates an instance of CIMServer and starts it executing.

2. pegwmiserver.dll is the mapper equivalent of pegserver.dll. The cimOperationRequestDispatcher module has been rewritten to eliminate the provider service and to access the WMI interfaces directly.

3. WMIProvider.dll is the interface dll to WMI. Its methods are called from the cimOperationRequestDispatcher module, and it handles all WMI calls.

4. pegwmiclient.dll provides a replacement for the CIMClient class/API, which allows for direct connections to a local WMI Mapper (using the CIMClient::connectLocal() API), without going through HTTP/HTTPS (performance and security enhancement). C++ clients that will use the CIMClient API should link to pegwmiclient.lib, rather than to pegclient.lib.

## Installing and running the WMI Mapper

#### Installing Runtime Files

If the WMI Mapper was built on the same machine it will be run on, then all the files needed to run the mapper will already be under %PEGASUS_HOME% directory, and the Mapper may be run from there (Exception: you may want to copy the OpenSSL .dll’s from OPENSSL_HOME to %PEGASUS_HOME%\bin, or otherwise ensure that the OpenSSL .dll’s are somewhere in the system PATH).

Otherwise, if the WMI Mapper will be installed on another machine, the following files will need to be copied from %PEGASUS_HOME%\bin on the build machine, to %PEGASUS_HOME%\bin on the target machine:

§ pegauthentication.dll

§ pegclient.dll

§ pegcliutils.dll

§ pegcommon.dll

§ pegconfig.dll

§ pegexportserver.dll

§ peggetoopt.dll

§ pegprovider.dll

§ pegrepository.dll

§ peguser.dll

§ pegwmiclient.dll

§ pegwmiserver.dll

§ wbemexec.exe

§ wmiop.exe

§ WMIProvider.dll

§ WMIServer.exe

If the WMI Mapper was built with SSL support (PEGASUS_HAS_SSL), you will also need to copy the following files from %OPENSSL_HOME% to %PEGASUS_HOME%\bin on the target machine:

§ libeay32.dll

§ openssl.exe

§ ssleay32.dll

You will also need to generate SSL certificate files on the target machine (using openssl.exe). See pegasus/readme.html for information on generating SSL certificates, and configuring the server to use HTTPS/SSL.

NOTE: You may also need to copy msvcp60.dll (runtime library, installed by Visual C++ on the development machine in the system32 directory) to %OPENSSL_HOME%\bin, or somewhere in the PATH on the target machine

#### Runtime Environment Variables

§ PEGASUS_HOME must be set to the root directory where the Mapper files were copied

§ Add %PEGASUS_HOME%\bin to the PATH

#### Configuring the WMI Mapper Server

Since WMIServer.exe is based on the standard Pegasus server (cimserver), it is configured in the same way -- using cimserver_planned.conf and cimserver_current.conf files in the %PEGASUS_HOME% directory. For an initial installation, you will want to generate or copy an initial set of configurations files to be installed in the %PEGASUS_HOME% directory on the target machine. Here is an example of an initial config files (cimserver_planned.conf and cimserver_current.conf should be identical):

########################################################################

## ##

## CIM Server configuration file ##

## ##

########################################################################

########################################################################

# #

# This is the configuration file for the CIMOM. The configuration #

# properties in this file are loaded in to CIMOM at startup. #

# CIMOM updates this file with the changes in the configurations. #

# #

########################################################################

httpsPort=5989

enableHttpsConnection=true

enableHttpConnection=false

sslCertificateFilePath=cert.pem

    sslTrustFilePath=client.pem

sslKeyFilePath=file.pem

#### Running the WMI Mapper Server

To install the WMI Mapper as a Windows Service:

§ > %PEGASUS_HOME%\wmiserver -install

To start the WMI Mapper Service:

§ > %PEGASUS_HOME%\wmiserver -start

To stop the WMI Mapper Service:

§ > %PEGASUS_HOME%\wmiserver -stop

To un-install the WMI Mapper as a Windows Service:

§ > %PEGASUS_HOME%\wmiserver -remove

To see all WMI Mapper command line options:

§ > %PEGASUS_HOME%\wmiserver -h

To run the WMI Mapper from a command line – NOT as a service:

§ > %PEGASUS_HOME%\wmiserver