PEP

Pegasus Enhancement Proposal (PEP)

PEP#: 356

PEP Type: Functional

Title: Provider module grouping

Status: Approved

Version History:

Version	Date	Author	Change Description
0.1	18 March 2010	Venkat Puvvada	Initial Submission
1.0	1 April 2010	Venkat Puvvada	Incorporated review comments
1.1	9 April 2010	Venkat Puvvada	incorporated review comments/Ballot version

Abstract: Add support to OpenPegasus to run different provider modules under the same provider-agent while running out-of-process.

Definition of the Problem

A provider module contains one or more providers and is implemented as a single shared object or DLL. Currently each provider module is loaded into a different provider agent processes when the CIM Server is built and configured for Out-Of-Process (OOP). Providers residing within a single provider module cannot be selectively unloaded.

Under these circumstances, providers are therefore usually packaged in one in the following two ways:

All providers are packaged into a single provider module. This has the following disadvantages.

Disabling an individual provider does not actually unload its functionality, its symbols remain present in the global symbol table and the virtual address space usage is not reduced.
Identification of misbehaving providers is often difficult because the providers cannot be selectively disabled and replaced.

Each provider is packaged into its own provider module. This has the following disadvantages:

On some platforms creating a process is more expensive or may reach the max process limit.
A singleton resource access layer or instrumentation layer cannot be shared between all related-providers.

JMPI providers which are run in Out-of-Process mode today require a JVM in each provider agent process which consumes a lot of memory. Providers from different vendors cannot be packaged into a single provider module, thus providers from different vendors today require multiple provider agent processes.

Proposed Solution

Provider module grouping solves the above mentioned problems by allowing the execution of multiple provider modules under single agent process.

Note: With this approach, a single faulty provider can bring down all other providers running in the same provider-agent. But currently this already happens when all providers are built into single provider module.

Modify Pegasus so that multiple provider modules can be executed in a single agent process (i.e. module grouping), provide the means so that this grouping can be defined as part of the provider registration and even dynamically to providers already registered with a modification to the PG_ProviderModule class.

The following property and method are added to the PG_ProviderModule class.

      [Description(
        "   A string specifying a group name for the provider module. If the specified "
        "value is \"CIMServer\", provider module is loaded into the CIMServer "
"process. Provider modules having the same group name other than "
        "\"CIMServer\" are loaded into a single agent process depending on UserContext"
        "value. If the value is not specified, each provider module is loaded into different"
        " agent process. Provider modules having different UserContext values but the"
       " same group name are loaded according to the UserContext information")]
   string ModuleGroupName;

   [Description(
       "Sets the module group name")]
   sint16 setModuleGroupName([IN] string moduleGroupName);

Provider module grouping depends on the UserContext information. UserContext property does not overrule the Module Grouping, but just causes multiple provider processes to exist, one per user. In simple terms provider grouping preserves the UserContext behavior. See PEP 197 for more details on UserContext property.

For example, If UserContext value is set to 2(Requestor) , provider module is loaded out-of-process irrespective of forceProviderProcesses config property value. Similarly, if the ModuleGroupName value is set to "CIMServer" or any other name and UserContext value is set to 2(Requestor), provider module is loaded out-of-process. See the table defined in PEP 197 for more information on how the provider agents are created based on UserContext and froceProviderProcesses config property value. Same semantics are followed with this enhancement except that provider module is invoked with its group name.

Provider module group changes are logged and audit logging is also done.

ProviderModule Caching

Since the provider module instance rarely changes, providerModule instance is cached on both server and agent side. An optimization is used to send it only when it differs from the last provider module instance sent to the agent. This implementation does not change this logic.

Backward compatibility with existing registrations

Existing provider registrations will continue to work. If ModuleGroupName property value is not specified or NULL, provider module name is used while creating the provider agent and each provider module is loaded into different agent process as done currently.

Modifications to cimprovider command

To facilitate easy change of provider module grouping during runtime of cimserver, cimprovider command is modified to support the runtime change of provider module grouping. Option "-g" is added to support grouping of provider modules and "-f" is added to display the full status of provider modules with the group name.

Usage: cimprovider -g group -m module
                     -l [ -s | -f | -m module ]
Options:
    -g         - Sets the CIM provider module group.
                 Specify empty string to remove from grouping.
                 If the provider module is active, provider
                 module is disabled first, group is set and
                 enabled again. All provider modules with the same
   group name are loaded into a single agent process
   except when overridden by specific UserContext
   values. If group name is CIMServer,
                 provider module is loaded into CIMServer process
                 depending on UserContext value.
    -f         - Full status, display the status of registered provider
                 modules and module group name

Schedule

Available in 2.11

Future Ideas

Modify cimprovider command to list whether the provider agent is active and show PID of agent process if running OOP.
cimprovider or some other command which lists the classes instrumented by the provider.

Discussion

For provider module grouping, a list of provider modules can be cached on both server and agent side. With the internal binary protocol enabled, the cost of writing the provider module instance to the agent (through pipe) is not expensive as done as before with CIM-XML.

Comments from Version 0.1

(k_schopmeyer) Question: Are there cases that should be considered where the provider/module writer would want to limit the use of this functionality by admininstrators? Not sure myself so just asking for now.
(Venkat_Puvvada) May be, we can work on this feature in future versions.

(tim_potter) Now this is getting confusing. Surely the UserContext property should be able to override the module grouping as it's a security setting. Perhaps a table might help clear things up.
(venkat_puvvada) Table defined in PEP 197 applies here, except that providers having the same group name loaded into single agent process because group name is used instead of module name while invoking the provider agent.

(tim_potter) What's the use case for being able to change module groupings dynamically? I've used the equivalent functionality in SFCB and the module grouping is determined at compile time and can't be changed. I don't think it makes sense to be able to change provider groups as no other aspect of provider registration can be modified in this way.
(venkat_puvvada) This enables the admin easy change of groupings at run time without restarting the CIMServer, troubleshooting and isolating the provider would be easier .
Currently we allow OperationalStatus of provider module to be changed through cimprovider command.
(k_schopmeyer) I think that making variables like this dynamic may really help with some of the issues we have with adminstering pegasus.

(sahana_prabhakar) Will cimprovider -l be modified to list the group name ? What if the provider module is already loaded when the cimprovider command is run to add it to a group. Will this be allowed ?
(venkat_puvvada) Yes, good point, I think group name should be displayed. When provider is already loaded , changing the group name will result in the following operations. < br> 1. Disable provider module (There should not be any pending operations which is current behavior)
2. Change the group name.
3. Enable the provider module.

Comments on version 1.0

(k_schopmeyer) Questions:
Should we have any charcter limits on the names (ex. should ! &#%, etc. be allowed in the names)? Do caps and lower case make a difference in the names. i.e. is there a difference in the way this operates in windows and unix because of case issues? I am assuming no but better to ask now rather than later.
(venkat_puvvada) There will not be any difference on Linux and Windows, its just a name given to cimprovagt process during the creation.

(k_schopmeyer) Logging Are we logging all of these changes???
Finally, here is a thought. We show specific information in the cimprovider (es. the -f option) but we don't show which provider agent is actually used by a particular provider if force or UserContext overrides the group name I don't think.
(venkat_puvvada) Yes, audit logging is done when module group changes. Good idea, -f options shows the group name of the provider and not the agent process-id. I want to extend this option in future to report whether the provider is active(in memory) or not.

Permission is hereby granted, free of charge, to any person obtaining a copy of

this software and associated documentation files (the "Software"), to deal in

the Software without restriction, including without limitation the rights to

use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of

the Software, and to permit persons to whom the Software is furnished to do so,

subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS

FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR

IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN

CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Template last modified: February 17th 2009 by Martin Kirk
Template version: 1.15