TITLE: RUNNING CIMSERVER AS A SERVICE ON WINDOWS

Version :  1.3

Authors: Tony Fiorentino

State:  Approved

Type: Design

Created: 1/13/03

Version History:

version        date                authors                Reason

1.3              01/25/03         Tony Fiorentino  Final review comments

1.2              01/23/03         Tony Fiorentino  More review comments

1.1              01/17/03         Tony Fiorentino  Review comments

1.0              01/13/03         Tony Fiorentino  Draft Proposal

Abstract: The Pegasus CIMOM server (cimserver.exe) currently runs predictably from a command window "daemon-like", but unpredictably as a service under the SCM. This PEP documents an environment determination strategy to run cimserver.exe as a windows service.

Problem:
cimserver.exe does not run predictably as a service based on working directory or configuration settings. The existing code works only for a very specific environment, which includes requiring the config file and repository in the windows system directory.

Assumptions:
- Supported windows platforms: NT/2000/XP.  Basically, any 9x windows platforms are unsupported.
- Running from a command window is supported, but is intended for initial feature development, debug, and test.
- Pegasus could be installed anywhere on a client's windows machine.
- The directory of cimserver.exe is the same as it's DLL dependencies (including providers, unless the "providerDir" is set in the config file)
- The solution will work from a development source tree or client installation (more of a requirement than an assumption)

Solution:
- Start monitor asynchronously.
- Add two new windows service control arguments: -start (daemon is false) and -stop.   Use -start to start the cimserver as windows service (same as "net start cimserver").  Use -stop to stop the cimserver service (same as "net stop cimserver").  (Note that there is already a -s for shutdown and that will be used to stop the cimserver that is running as a daemon.
- If running in a "console window" and no arguments (argc == 1) are supplied, cimserver.exe will start as a daemon.
- Eliminate the dependency on the PEGASUS_HOME environment variable. This is the intention of the original design, but a -install without PEGASUS_HOME set would put /bin/cimserver.exe into the registry. In general, environment variables can be used, but will be overridden by config settings.
- Eliminate the dependency on a config file. A config file can exist but if NOT present, defaults prevail.
- Attempt to send service startup/shutdown related messages (errors/warnings) to the Windows Application event log.  All other messages will work as they do for the current pegasus log/trace facility.
- Determine runtime environment dependencies in a predictable fashion before starting:

Windows Service:
- look for config file in Pegasus "home" directory (See Pegasus "home" Search Rules below)
- find config file?
- NO: Use default operating settings
- YES: Use config settings

Pegasus "home" Search Rules:
1. Registry Key (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\cimserver\home)
2. Home Directory - If PEGASUS_HOME environment variable is not set, then internally, the pegasus home will be set to the dirname of <exe dir> (i.e., one back from <exe_dir>) (where <exe dir> is the dirname of the absolute path of the running cimserver program).

- Note: cimserver -install sets the "home" registry key.

Advantages:
The advantage of the proposed solution is it requires minimal configuration with predictable behavior. At any time, the cimserver.exe can be installed/started/run/stopped/removed all from the exe directory without any required environment settings. If environment settings are made, they are made through the config file which is found via a predefined search rule.  Running as a service prevents the user from inadvertently closing the cimserver program prematurely (as can happen when running from a command window). It can be argued that running as a "daemon" within a command window is reserved for debug since any stderr/out debug messages will appear in the command window, allowing a developer to see debug tracing from a provider dependency (like an api library), etc.

Disadvantages:
You cannot see stdout/stderr debug messages when running as service.  The developer will need to run from a command window ("daemon-like") to see such messages.

Schedule:
Approximately one week of coding and one week of debug, test, and check-in. Since I have already started some of this work, I would like to get this build tested, checked in and solid by January 31st, 2003.

Miscellaneous:
Shared Libraries:
- The cimserver is dependent on shared libraries.
- The windows OS loader is responsible for resolving implicit runtime library dependencies.
- dependent shared libraries: pegcommon, pegconfig, pegserver, pegclient, slp
Since the distribution is assumed to have the DLLs in the same directory as the cimserver.exe, these dependencies will be resolved via the default behavior of the loader.
- Provider libraries are shared libraries and are loaded explicitly by the provider manager.
- exported symbol is hard-coded - "PegasusCreateProvider"
- Library name is configured in the capabilities instance of the interop namespace
- providerLib config setting is prepended to the library name above to set the full path of the DLL