3.9 Helper providers


3.9 Helper providers

Until now, each time we worked with a WMI provider, it collected information about a specific managed object in a computer. WMI also comes with a collection of providers designed to support some WMI internal features. In this section, we will examine the two most useful features from a WMI consumer perspective: the View provider to support the concept of views and the Forwarding consumer provider to perform events forwarding. We will also briefly examine the event Correlator providers.

3.9.1 The View provider

The main capability of the View provider is its ability to take properties from different source classes, different namespaces, and different computers and combine all information in one single class. Basically, the concept of the View provider looks very similar to the concept of views developed for the relational database. Of course, this comparison must be limited here, since its implementation is totally different. To take advantage of the View provider, it must first be registered in the CIM repository. The registration can be done with the MOFCOMP.EXE tool and the MOF file shown in Sample 3.82.

Sample 3.82: Registering the View provider

start example

  1:#pragma namespace("\\\\.\\Root")  2:  3:Instance of __Namespace  4:{  5: Name = "View";  6:};  7:  8:#pragma namespace("\\\\.\\ROOT\\View")  9: 10:Instance of __Win32Provider as $DataProv 11:{ 12:  Name = "MS_VIEW_INSTANCE_PROVIDER"; 13:  ClsId = "{AA70DDF4-E11C-11D1-ABB0-00C04FD9159E}"; 14:  ImpersonationLevel = 1; 15:  PerUserInitialization = "True"; 16:  HostingModel = "NetworkServiceHost"; 17:}; 18: 19:Instance of __InstanceProviderRegistration 20:{ 21:  Provider = $DataProv; 22:  SupportsPut = TRUE; 23:  SupportsGet = TRUE; 24:  SupportsDelete = TRUE; 25:  SupportsEnumeration = TRUE; 26:  QuerySupportLevels = {"WQL:UnarySelect"}; 27:}; 28: 29:Instance of __MethodProviderRegistration 30:{ 31:  Provider = $DataProv; 32:}; 

end example

You will note that the MOF file creates a new namespace for the provider (lines 3 through 6). This new namespace is not mandatory, since the registration can be done in any existing namespace. However, using a dedicated namespace clarifies the CIM repository organization, since only the classes created for the View provider will be available from this namespace. By default, there are few classes in the CIM repository supported by the View provider. These created classes are called the View classes. For example, the WMI information about the Internet Information Server (IIS) takes advantage of the View provider by accessing the Win32_Service instances in the Root\CIMv2 namespace from the Root\MicrosoftIISv2 namespace. The View provider is the component handling the cross-namespace access. As shown in Table 3.79, the View provider is implemented as an instance and a method provider.

Table 3.79: The View Providers Capabilities

Provider Name

Provider Namespace

Class Provider

Instance Provider

Method Provider

Property Provider

Event Provider

Event Consumer Provider

Support Get

Support Put

Support Enumeration

Support Delete

Windows Server 2003

Windows XP

Windows 2000 Server

Windows 2000 Professional

Windows NT 4.0

View Provider

ViewProv

Not defined

X

X

X

X

X

X

X

X

X

X

X

As we will see, the View provider and the creation of the View classes are not directly related to the WMI scripting. However, once the View classes are created, any script can benefit from their existence.

We distinguish three types of view classes:

  • The Join view classes: These classes represent the instances of different classes connected by a common property value.

  • The Union view classes: These classes represent the union of one or more classes across the namespace boundary.

  • The Association view classes: These classes represent views of existing association classes across the namespace boundary.

Because the View classes have these specific purposes, they use some specific qualifiers for their creation (see Table 3.80).

Table 3.80: The View Provider Qualifiers

Qualifier

Comments

Direct

Data type: Boolean Used with view association properties to prevent association references from being mapped to a view reference.

HiddenDefault

Data type: Boolean Default value for a view class property based on a source class property with a different default value. The underlying source class is implied by the view.

JoinOn

Data type: string Defines how source class instances should be joined in join view classes. The following example shows how to use the JoinOn qualifier to join two source classes from the Performance Monitoring Provider.

MethodSource

Data type: string array Source method to execute for the view method. For similar syntax, see PropertySources Qualifier. The signature of the method must match the signature of the source class exactly. Copy the method signature from the MOF file that defines the source class. This qualifier is only valid when it is used with union views.

PostJoinFilter

Data type:string WQL query to filter instances after they have been joined in a join class.

PropertySources

Data type: string array Source properties from which a view class property gets data.

Union

Data type: Boolean Indicates whether you are defining a union class. Union views contain instances based on the union of source instances. For example, you might declare the following.

ViewSources

Data type: string array Set of WMI Query Language (WQL) queries that define the source instances and properties used in a specific view class. Positional correspondence of all the array qualifiers is important.

ViewSpaces

Data type: string array Namespaces where the source instances are located.

Sample 3.83 shows a MOF file creating a Join view class. In this sample, the View provider joins the Win32_PerfRawData_PerfProc_Process class with the Win32_PerfRawData_PerfProc_Thread class. Because the join requires a common property value between the two classes, the IDProcess property is used as the common property.

Sample 3.83: The Join View class

start example

  1:#pragma namespace("\\\\.\\Root\\View")  2:  3:[  4: JoinOn("Win32_PerfRawData_PerfProc_Process.IDProcess=                                                  Win32_PerfRawData_PerfProc_Thread.IDProcess"),  5: ViewSources{  6:            "SELECT Name, IDProcess, PriorityBase                                                  FROM Win32_PerfRawData_PerfProc_Process" ,  7:            "SELECT Name, IDProcess, ThreadState, PriorityCurrent                                                  FROM Win32_PerfRawData_PerfProc_Thread"  8:            },  9: ViewSpaces{ 10:           "\\\\.\\Root\\cimv2", 11:           "\\\\.\\Root\\cimv2" 12:           }, 13: dynamic: ToInstance, 14: provider("MS_VIEW_INSTANCE_PROVIDER") 15:] 16: 17:class JoinedProcessThread 18:{ 19: [read, PropertySources{"IDProcess",    "IDProcess"}] Uint32 ProcessID; 20: [read, PropertySources{"Name",         ""}] String ProcessName; 21: [read, PropertySources{"",             "Name"}, key] String ThreadName; 22: [read, PropertySources{"",             "ThreadState"}] Uint32 State; 23: [read, PropertySources{"PriorityBase", ""}] Uint32 BasePriority; 24: [read, PropertySources{"",             "PriorityCurrent"}] Uint32 CurrentPriority; 25:}; 

end example

At line 4, we see the JoinOn qualifier stating the link between the two classes on the IDProcess property. Because the MOF file links two instances coming from two different classes, lines 5 through 8 use the ViewSources qualifier to locate each instance coming from each respective class. This qualifier contains the WQL queries to locate instances of each class. Since every instance must be located in its respective namespaces, the ViewSpaces qualifier contains the WMI namespaces in which to look. At line 13, the View class is defined as a dynamic View class with the Dynamic qualifier. Next, the provider qualifier defines the View provider to support this new class definition.

From line 17 through 25, the class itself is defined. Each property of the class definition uses the PropertySources qualifier to map the desired property of the original class to a property of the View class. Note that in this example, each qualifier supported by the View provider is an array containing two items, where each of them corresponds to information related to the original classes. Once the MOF file is loaded in the CIM repository, the JoinedProcessThread class will be accessible from the Root\View namespace (see Figure 3.56).

click to expand
Figure 3.56: The new created Join View class.

We can reuse the script developed in Chapter 1 (Sample 1.5, "Listing all instances of a class with their properties formatted") to display instances of this View class:

  1:   C:\>GetCollectionOfInstances.wsf JoinedProcessThread /NameSpace:Root\View  2:   Microsoft (R) Windows Script Host Version 5.6  3:   Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.  4:  5:  6:   BasePriority: ............................ 0  7:   CurrentPriority: ......................... 0  8:   ProcessName: ............................. Idle  9:   ProcessID: ............................... 0 10:   State: ................................... 2 11:   *ThreadName: ............................. Idle/0 12: 13:   BasePriority: ............................ 0 14:   CurrentPriority: ......................... 0 15:   ProcessName: ............................. Idle 16:   ProcessID: ............................... 0 17:   State: ................................... 0 18:   *ThreadName: ............................. _Total/_Total 19: 20:   BasePriority: ............................ 8 21:   CurrentPriority: ......................... 0 22:   ProcessName: ............................. System 23:   ProcessID: ............................... 4 24:   State: ................................... 1 25:   *ThreadName: ............................. System/0 26: 27:   BasePriority: ............................ 8 28:   CurrentPriority: ......................... 13 29:   ProcessName: ............................. System 30:   ProcessID: ............................... 4 31:   State: ................................... 5 32:   *ThreadName: ............................. System/1 33: 34:   BasePriority: ............................ 8 35:   CurrentPriority: ......................... 13 36:   ProcessName: ............................. System ..: ..: ..: 

If you compare the properties of each original class with the content of the MOF file sample, you will see that each instance contains a mix of the properties coming from the Win32_PerfRawData_PerfProc_Process and Win32_PerfRawData_PerfProc_Thread classes joined by the IDProcess property. In other words, you consolidate the data from two different instances into one.

The second View class type is the Union class. Sample 3.84 shows a MOF file example to create a Union View class.

Sample 3.84: The Union View class

start example

  1:#pragma   namespace("\\\\.\\Root\\View")  2:  3:[  4: Union,  5: ViewSources{  6:            "SELECT * From Win32_LogicalDisk Where DeviceID='C:'",  7:            "SELECT * From Win32_LogicalDisk Where DeviceID='C:'"  8:            },  9: ViewSpaces{ 10:           "\\\\net-dpen6400a.LissWare.Net\\Root\\CIMv2", 11:           "\\\\net-dpep6400.Emea.LissWare.Net\\Root\\CIMv2" 12:           }, 13: dynamic: ToInstance, 14: provider("MS_VIEW_INSTANCE_PROVIDER") 15:] 16: 17:Class UnionDrives_C 18:{ 19: [read, PropertySources{"Description", "Description"}] string Description; 20: [read, PropertySources{"DeviceID", "DeviceID"}, key] String DeviceID; 21: [read, PropertySources{"VolumeSerialNumber", "VolumeSerialNumber"}, key] string VolumeSN; 22: [read, PropertySources{"FileSystem", "FileSystem"}] String FileSystem; 23: [read, PropertySources{"FreeSpace", "FreeSpace"}] uint64 FreeSpace; 24: [read, PropertySources{"VolumeName", "VolumeName"}, key] String VolumeName; 25: [read, PropertySources{"__SERVER", "__SERVER"}, key] String Server; 26:}; 

end example

The Union qualifier doesn't use any parameter. However, it also works in conjunction with the ViewSources and the ViewSpaces qualifiers (lines 5 and 9). Although the ViewSources qualifier continues to use a WQL statement to locate the required instances (lines 5 through 8), it is important to note the following:

  • The ViewSources qualifier selects the "C:" drive instances only (see WQL data query).

  • The ViewSpaces qualifier locates these instances in the same namespaces but on two different systems (lines 9 through 12).

As a result, the UnionDrives_C class (defined from line 17 through 25) will list a collection of two "C:" drive instances coming from the two different systems defined in the ViewSpaces qualifier. Note the presence of the __SERVER system property, exposed as the "server" Key property (line 25), and the definition of the VolumeSerialNumber property as another Key property to distinguish each View class instance (line 24). Originally, the Key property of the Win32_LogicalDisk source class was the DeviceID property, which is the drive letter of the logical disk. Now, because the View class retrieves a collection of "C:" drive instances, the DeviceID property can't be used, since it is the only Key property originally used to distinguish the various instances. This means that other uniqueness criteria must be created. This is why the server and the VolumeSerialNumber properties are also defined as Key properties. The output would be as follows:

  1:   C:\>GetCollectionOfInstances.wsf UnionDrives_C /NameSpace:Root\View  2:   Microsoft (R) Windows Script Host Version 5.6  3:   Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.  4:  5:  6:   Description: ............................. Local Fixed Disk  7:   *DeviceID: ............................... C:  8:   FileSystem: .............................. NTFS  9:   FreeSpace: ............................... 827183616 10:   Server: .................................. NET-DPEN6400A 11:   *VolumeName: ............................. Windows 2003 12:   *VolumeSerialNumber: ..................... 988BD271 13: 14:   Description: ............................. Local Fixed Disk 15:   *DeviceID: ............................... C: 16:   FileSystem: .............................. NTFS 17:   FreeSpace: ............................... 725999616 18:   Server: .................................. NET-DPEP6400 19:   *VolumeName: ............................. Windows 2003 20:   *VolumeSerialNumber: ..................... 74052931 

By addressing one single class from one namespace, we get a collection of instances coming from two different systems. However, it looks like this information is coming from the local system. It must be clear that the credentials used to connect to the Root\View namespace must also be valid to connect to the remote Root\CIMv2 namespaces!

The last View class type supported by the View provider is the Association view class. Basically, what we did before with the previous classes (see Sample 3.84) can be done with the association classes. This class creation is illustrated in Sample 3.85.

Sample 3.85: The Association View class

start example

  1:#pragma namespace("\\\\.\\Root\\View")  2:  3:[  4: Union,  5: ViewSources{  6:            "SELECT * From Win32_LogicalDisk Where DeviceID='C:'"  7:             },  8: ViewSpaces{  9:           "\\\\.\\Root\\CIMv2" 10:           }, 11: dynamic, 12: provider("MS_VIEW_INSTANCE_PROVIDER") 13:] 14: 15:Class UnionDrive_C 16:{ 17: [read, PropertySources{"Description"}] string Description; 18: [read, PropertySources{"DeviceID"}, key] String DeviceID; 19: [read, PropertySources{"VolumeSerialNumber"}, key] string VolumeSerialNumber; 20: [read, PropertySources{"FileSystem"}] String FileSystem; 21: [read, PropertySources{"FreeSpace"}] uint64 FreeSpace; 22: [read, PropertySources{"VolumeName"}, key] String VolumeName; 23: [read, PropertySources{"__SERVER"}, Key] String Server; 24: 25: [Implemented, 26:  MappingStrings{"Fmifs.dll | Method ChkDskExRoutine"}: ToSubClass, 27:  MethodSource{"Chkdsk"}] uint32 ViewChkdsk([in] boolean FixErrors = FALSE, 28:                                            [in] boolean VigorousIndexCheck = TRUE, 29:                                            [in] boolean SkipFolderCycle = TRUE, 30:                                            [in] boolean ForceDismount = FALSE, 31:                                            [in] boolean RecoverBadSectors = FALSE, 32:                                            [in] boolean OkToRunAtBootUp = FALSE); 33:}; 34: 35:[ 36: Association, 37: ViewSources { 38:             "SELECT * FROM Win32_DiskQuota" 39:             }, 40: ViewSpaces { 41:            "\\\\.\\Root\\CIMv2" 42:            }, 43: dynamic, 44: provider("MS_VIEW_INSTANCE_PROVIDER") 45:] 46: 47:class Association_UnionOfDriveQuota 48:{ 49:    [key, PropertySources{"QuotaVolume"}] 50:    UnionDrive_C ref Drive; 51: 52:    [Direct, key, PropertySources{"User"}] 53:    Win32_Account ref User; 54:}; 

end example

The MOF file sample contains two main parts:

  • A Union View class creation, made from the Win32_LogicalDisk class (lines 3 through 33). Basically, this Union View class creation follows the same rules as Sample 3.84. However, the instances of this class are coming from one single namespace in one single computer (lines 8 through 10). So, this technique maps a class from one namespace (Root\CIMv2) to make it available to another namespace (Root\View). The Association View class created in the second part of the MOF file references this Union class.

    The interesting addition in this Union class is the mapping of the Chkdsk method defined in the Win32_LogicalDisk class. In the previous sample, we only mapped some properties. In this example, we also map a method with the help of the MethodSource qualifier. Note that it is important to use a method definition in the View Class that exactly matches the method definition in the original class, which is, in this example, the Win32_LogicalDisk class. The best method is to take a MOF file export of this class, cut the method definition from this exported MOF file, and paste it into your MOF file. As a result, the Chkdsk method is mapped to the View class as the ViewChkdsk method (lines 27 through 32).

  • An Association View class, made from the Win32_DiskQuota association class, associates the previously created UnionDrive_C View class with the Win32_Account class. The link with the Win32_Account class is defined with the User reference originally coming from the Win32_DiskQuota class (lines 35 through 54). If you go back to the Win32_DiskQuota association class and look at what this class associates, you will see that two classes are linked together:

    • The Win32_LogicalDisk class with the QuotaVolume reference

    • The Win32_Account class with the User reference

    However, the QuotaVolume reference is overwritten by the Drive reference defined in the association View class, while the User reference is kept intact in the Win32_DiskQuota association class by the presence of the Direct qualifier. You can compare the Association_UnionOfDriveQuota association View class with the Win32_DiskQuota association class shown in Figure 3.57.

    click to expand
    Figure 3.57: The Win32_DiskQuota association class and the created Association View class.

From a scripting perspective, we obtain the following output for the newly created Association View class:

 1:   C:\>GetCollectionOfInstances.wsf Association_UnionOfDriveQuota /NameSpace:Root\View 2:   Microsoft (R) Windows Script Host Version 5.6 3:   Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. 4: 5: 6:   *Drive: .................................. \\NET-DPEN6400A\Root\VIEW:UnionDrive_C.DeviceID=               "C:",Server="NET-DPEN6400A",VolumeName="Windows 2003",VolumeSerialNumber="988BD271" 7:   *User: ................................... Win32_Account.Domain=                                                            "NET-DPEN6400A",Name="Administrators" 

This last example illustrates how it is possible to associate classes from different namespaces with the View provider.

3.9.2 The Forwarding consumer provider

The Microsoft WMI Forwarding consumer provider is available under Windows XP.

Registered in the Root\Subscription namespace, it allows local WMI events to be forwarded to remote systems. In remote systems the Microsoft WMI Forwarding event provider, registered in the Root\CIMv2 namespace, triggers the received forwarded event as an instance of the MSFT_ForwardedEvent extrinsic event class. To trace the Microsoft WMI Forwarding consumer provider activity, the Microsoft WMI Forwarding Consumer Trace event provider, also registered in the Root\Subscription namespace, generates WMI events with a specific set of extrinsic event classes to any WMI consumers subscribing to these event notifications.

Table 3.81 summarizes the characteristics of the Microsoft WMI Forwarding Consumer, Microsoft WMI Forwarding Event, and Microsoft WMI Forwarding Consumer Trace event providers. Table 3.82 lists classes supported by these three providers implemented in one single DLL (FwdProv.DLL).

Table 3.81: The WMI Forwarding Consumer and Forwarding Event Providers Capabilities

Provider Name

Provider Name Space

Class Provider

Instance Provider

Method Provider

Property Provider

Event Provider

Event Consumer Provider

Support Get

Support Put

Support Enumeration

Support Delete

Windows Server 2003

Windows XP

Windows 2000 Server

Windows 2000 Professional

Windows NT 4.0

Microsoft WMI Forwarding Consumer Provider

FwdProv

Root/Subscription

X

X

Microsoft WMI Forwarding Consumer Trace Event Provider

FwdProv

Root/Subscription

X

X

Microsoft WMI Forwarding Event Provider

FwdProv

Root/CIMV2

X

X

Table 3.82: The WMI Forwarding Consumer and Forwarding Event Providers Classes

Microsoft WMI Forwarding Consumer Provider class

Name

Description

MSFT_ForwardingConsumer

Represents an event consumer that forwards messages to target computer(s).

Microsoft WMI Forwarding Consumer Trace Event Provider classes

Name

Description

Select * From MSFT_FCTraceEventBase

MSFT_FCTraceEventBase

Base class for all forwarding consumer trace events.

MSFT_FCExecutedTraceEvent

Represents an execution of the forwarding consumer.

MSFT_FCTargetTraceEvent

Represents an attempt to forward a message to a target.

Microsoft WMI Forwarding Event Provider class

Name

Description

MSFT ForwardedMessageEvent

Base class for all forwarded messages.

MSFT ForwardedEvent

Indicates the arrival of a forwarded event.

Event forwarding involves at the minimum two systems: a source machine and a target machine. Figure 3.58 illustrates the logical organization of the various elements involved in event forwarding.

click to expand
Figure 3.58: The WMI Forwarding providers roles and locations.

The source machine is the machine where the original WMI event notification occurs (i.e., SourceComputer01). This is also the machine that forwards the event. To do so, it is necessary to create an instance of the MSFT_ForwardingConsumer class supported by the Microsoft WMI Forwarding consumer provider. Basically, this instance determines which event notification will be forwarded and to which target machines it must be forwarded. Therefore, the Microsoft WMI Forwarding consumer provider consumes a specific WMI event notification to be forwarded to the target machine, as defined in the MSFT_ForwardingConsumer instance. At the other end, the target machine (i.e., TargetComputer01) is the system receiving the event forwarded by the Microsoft WMI Forwarding consumer provider in the source machine. The Microsoft WMI Forwarding event provider is in charge of receiving the forwarded event and triggering an event notification as an instance of the MSFT_ForwardedEvent extrinsic event class. Any WMI consumer who subscribed to receive the forwarded event will get a notification. More than simply notifying that an event has been forwarded, the subscriber will also find information inside the MSFT_ForwardedEvent about the instances (located in the source machine) subject to the event notification.

To configure this mechanism, the first step is to create an instance of the MSFT_ForwardingConsumer class with its __EventFilter associated class.

This can be done with a MOF file (see Sample 3.86). Of course, a script can create these instances as well.

Sample 3.86: A MOF file to forward WMI events

start example

  1:#pragma namespace ("\\\\.\\Root\\Subscription")  2:  3:Instance of MSFT_ForwardingConsumer as $SRCComputer01Consumer  4:  5:{  6:    // Indicates whether to include authentication information when forwarding the message.  7:       Authenticate = "True";  8:  9:    // Indicates whether to encrypt the message before forwarding. 10:       Encryption = "False"; 11: 12:    // The Quality-of-Service used to forward the message (0=Synchronous). 13:       ForwardingQoS = 0; 14: 15:    // Indicates whether to send schema information for the event to be forwarded. 16:       IncludeSchema = "False"; 17: 18:    // Name of the computer from which the message originates (inherited property). 19:    // MachineName = 20: 21:    // Maximum size of the queue in bytes. 22:    // MaximumQueueSize = 23: 24:    // A string uniquely identifying this consumer. 25:       Name = "SourceComputer01"; 26: 27:    // An array of addresses to forward the messages to. 28:    // The forwarding consumer will try to forward the message, in order, 29:    // to each address in the list until it successfully sends it to one of them. 30:       Targets = {"NET-DPEN6400A.LissWare.NET"}; 31: 32:    // A security descriptor, in SDDL format, that is attached to the 33:    // forwarded event when it is raised on the receiving end. 34:    // This security descriptor indicates to the receiver which security 35:    // identitiers are allowed to consume the forwarded event. 36:    // TargetSD = ""; 37:}; 38: 39:Instance of __EventFilter as $SRCComputer01Filter 40: 41:{ 42:    Name = "Forward all Win32_Service instance modifications"; 43:    Query = "Select * From __InstanceModificationEvent Within 5 " 44:                         "Where TargetInstance ISA 'Win32_Service'"; 45:    QueryLanguage = "WQL"; 46:    EventNamespace = "Root\\CIMv2"; 47:}; 48: 49:Instance of __FilterToConsumerBinding 50: 51:{ 52:    Consumer=$SRCComputer01Consumer; 53:    Filter=$SRCComputer01Filter; 54:}; 

end example

As with any WMI consumer providers, Sample 3.86 creates:

  • An instance of the MSFT_ForwardingConsumer class (derived from the __EventConsumer superclass) supported by the WMI consumer (lines 3 through 37)

  • An instance of the __EventFilter system class to define the WMI event notification to subscribe to (lines 39 through 47)

  • An instance of the __FilterToConsumerBinding association class to link the consumer with the WQL event notification filter (lines 49 through 54)

In this particular example, we are interested in the MSFT_ForwardingConsumer instance creation, since it contains all parameters related to the forwarding mechanism.

  • Authenticate (line 7): Authenticate indicates whether to include authentication information when forwarding the message. Is there a reason not to include the authentication information? Well, in some situations, it could be necessary to forward events between Active Directory Forests, where no trust exists between Forests. In such a case, it is necessary to set the Authenticate parameter to False. However, this is not enough to get this working. Since the authentication information is not contained in the message, to avoid an access-denied error message and ensure that the Microsoft WMI Forwarding Event in the target machine effectively triggers the event notification, it is necessary to set the AllowUnauthenticatedEvents registry key located in the HKLM\SOFTWARE\Microsoft\WBEM\FWD hive to 1. This will ensure that the Microsoft WMI Forwarding event provider accepts unauthenticated events. Note that if you change this registry key value, it is necessary to restart the WinMgmt.Exe service to make the change effective.

  • Encryption (line 10): Encryption indicates that packets between the source and the target machine are encrypted. The encryption is based on the COM Packet Privacy encryption mechanism. Note that by default, under Windows XP, the encryption is set to False.

  • ForwardingQoS (line 13): This property is not used, but it is reserved for future use and extensions. Its default value must be zero.

  • IncludeSchema (line 16): The IncludeSchema purpose is to send a CIM repository definition (which exists in the source machine) of the instances subject to the event. This ensures that the target machine understands the structure of the TargetInstance and PreviousInstance properties containing objects returned by the event forwarding notification in case these class definitions do not exist in the target machine. Keep in mind that setting IncludeSchema to True will represent a big overhead for the network. Therefore, it is best to set IncludeSchema to False for performance reasons. Note that setting IncludeSchema to False always includes the schema information for the first event with the condition that events are from the same source and class.

  • MaximumQueueSize (line 22): This property is reserved for future use and extensions. It should not be defined (the line is commented out in Sample 3.86).

  • Targets (line 30): Targets contain the list of computers that must be contacted as targets. This property acts as a "try list," which means that the forwarding consumer will try to forward the message, in order, to each address in the list until it successfully sends it to one of them. If you want to forward the same event to several computers, you must register several instances of the Forwarding Consumer (one per target). On the other hand, it is important to note that target machines, consuming forwarded events, are able to process MSFT_ ForwardedEvent events from multiple computers and networks.

  • TargetSD (line 36): TargetSD represents a security descriptor in security descriptor definition language (SDDL) format (see http://msdn.microsoft.com/library/en-us/security/Security/security_descriptor_string_format.asp for more information about SDDL). This security descriptor is attached to the forwarded event when it is raised on the target machine. It indicates to the receiver which security identifiers are allowed to consume the forwarded event.

Once the MOF file in Sample 3.86 is loaded with MOFCOMP.EXE in the CIM repository of the source machine, any Win32_Service instance modification events will be forwarded to the target machine. The only thing to do on the target machine is to run a WMI consumer subscribing to the event forwarding notification. In this example, we can reuse the GenericEventAsyncConsumer.wsf script (see Sample 6.17, "A generic script for asynchronous event notification" in the appendix). The WQL event query to formulate on the target machine must be as follows:

   1:   C:\>GenericEventAsyncConsumer.wsf "Select * From MSFT_ForwardedEvent Where Consumer = 'SourceComputer01'"   2:   Microsoft (R) Windows Script Host Version 5.6   3:   Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.   4:   5:   Waiting for events...   6:   7:   BEGIN - OnObjectReady.   8:   Thursday, 11 July, 2002 at 15:12:10: 'MSFT_ForwardedEvent' has been triggered.   9:     Account (wbemCimtypeUint8) = 1  10:     Account (wbemCimtypeUint8) = 5  11:     Account (wbemCimtypeUint8) = 0  ..:  34:     Account (wbemCimtypeUint8) = 3  35:     Account (wbemCimtypeUint8) = 0  36:     Account (wbemCimtypeUint8) = 0  37:     Authenticated (wbemCimtypeBoolean) = True  38:     Consumer (wbemCimtypeString) = SourceComputer01  39:     Event (wbemCimtypeObject)  40:       PreviousInstance (wbemCimtypeObject)  41:         AcceptPause (wbemCimtypeBoolean) = False  42:         AcceptStop (wbemCimtypeBoolean) = False  43:         Caption (wbemCimtypeString) = SNMP Service  44:         CheckPoint (wbemCimtypeUint32) = 0  45:         CreationClassName (wbemCimtypeString) = Win32_Service  46:         Description (wbemCimtypeString) = Enables Simple Network Management ...  ..:  60:         State (wbemCimtypeString) = Stopped  61:         Status (wbemCimtypeString) = OK  62:         SystemCreationClassName (wbemCimtypeString) = Win32_ComputerSystem  63:         SystemName (wbemCimtypeString) = NET-DPEP6400A  64:         TagId (wbemCimtypeUint32) = 0  65:         WaitHint (wbemCimtypeUint32) = 0  66:       SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null)  67:       TargetInstance (wbemCimtypeObject)  68:         AcceptPause (wbemCimtypeBoolean) = False  69:         AcceptStop (wbemCimtypeBoolean) = True  70:         Caption (wbemCimtypeString) = SNMP Service  71:         CheckPoint (wbemCimtypeUint32) = 0  72:         CreationClassName (wbemCimtypeString) = Win32_Service  73:         Description (wbemCimtypeString) = Enables Simple Network Management ...  ..:  87:         State (wbemCimtypeString) = Running  88:         Status (wbemCimtypeString) = OK  89:         SystemCreationClassName (wbemCimtypeString) = Win32_ComputerSystem  90:         SystemName (wbemCimtypeString) = NET-DPEP6400A  91:         TagId (wbemCimtypeUint32) = 0  92:         WaitHint (wbemCimtypeUint32) = 0  93:       TIME_CREATED (wbemCimtypeUint64) = (null)  94:     Machine (wbemCimtypeString) = NET-DPEP6400A  95:     Namespace (wbemCimtypeString) = ROOT\subscription  96:     SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null)  97:     Time (wbemCimtypeDatetime) = 11-07-2002 15:12:10 (20020711131210.000000+000)  98:     TIME_CREATED (wbemCimtypeUint64) = 11-07-2002 13:12:10 (20020711131210.953590+120)  99: 100:   END - OnObjectReady. 

There are two levels of information received:

  • The information about the forwarded event itself (lines 9 through 38 and lines 94 through 98)

  • The information about the instances subject to the event triggered in the source machine (lines 39 through 93), which is divided into two parts: the PreviousInstance (lines 40 through 65) and TargetInstance (lines 67 through 92)

In the source machine, with the help of the Microsoft WMI Forwarding Consumer Trace event provider and its set of supported classes, it is possible to trace the execution of the Microsoft WMI Forwarding consumer provider. By using a simple WMI consumer subscribing to the MSFT_FCExecutedTraceEvent or the MSFT_FCTargetTraceEvent extrinsic event classes, it is possible to gather information about an event forwarding execution. We can reuse the GenericEventAsyncConsumer.wsf script shown in Sample 6.17 ("A generic script for asynchronous event notification") in the appendix to catch this event in the source machine:

  1:   C:\>GenericEventAsyncConsumer.wsf "Select * From MSFT_FCTargetTraceEvent"                                         /Namespace:Root\Subscription  2:   Microsoft (R) Windows Script Host Version 5.6  3:   Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.  4:  5:   Waiting for events...  6:  7:   BEGIN - OnObjectReady.  8:   Friday, 12 July, 2002 at 11:35:26: 'MSFT_FCTargetTraceEvent' has been triggered.  9:     Consumer (wbemCimtypeObject) 10:       Authenticate (wbemCimtypeBoolean) = True 11:       CreatorSID (wbemCimtypeUint8) = 1 12:       CreatorSID (wbemCimtypeUint8) = 2 13:       CreatorSID (wbemCimtypeUint8) = 0 14:       CreatorSID (wbemCimtypeUint8) = 0 15:       CreatorSID (wbemCimtypeUint8) = 0 16:       CreatorSID (wbemCimtypeUint8) = 0 17:       CreatorSID (wbemCimtypeUint8) = 0 18:       CreatorSID (wbemCimtypeUint8) = 5 19:       CreatorSID (wbemCimtypeUint8) = 32 20:       CreatorSID (wbemCimtypeUint8) = 0 21:       CreatorSID (wbemCimtypeUint8) = 0 22:       CreatorSID (wbemCimtypeUint8) = 0 23:       CreatorSID (wbemCimtypeUint8) = 32 24:       CreatorSID (wbemCimtypeUint8) = 2 25:       CreatorSID (wbemCimtypeUint8) = 0 26:       CreatorSID (wbemCimtypeUint8) = 0 27:       Encryption (wbemCimtypeBoolean) = False 28:       ForwardingQoS (wbemCimtypeSint32) = 0 29:       IncludeSchema (wbemCimtypeBoolean) = False 30:       MachineName (wbemCimtypeString) = (null) 31:       MaximumQueueSize (wbemCimtypeUint32) = 65535 32:       *Name (wbemCimtypeString) = SourceComputer01 33:       Targets (wbemCimtypeString) = NET-DPEN6400A.LissWare.NET 34:       TargetSD (wbemCimtypeString) = (null) 35:     ExecutionId (wbemCimtypeString) = {F7EF6E36-FBAD-4C80-8196-BCC3B9A3A895} 36:     SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null) 37:     StatusCode (wbemCimtypeUint32) = 0 38:     Target (wbemCimtypeString) = 7879E40D-9FB5-450a-                                   8A6D-00C89F349FCEncacn_ip_tcp:NET-DPEN6400A.LissWare.NET 39:     TIME_CREATED (wbemCimtypeUint64) = 12-07-2002 09:35:26 (20020712093526.907875+120) 40:   END - OnObjectReady. 

The MSFT_FCTargetTraceEvent extrinsic event class represents an attempt to forward a message to a target machine, while the MSFT_FCExecutedTraceEvent extrinsic event class represents an execution of the forwarding consumer. Therefore, the latter contains information about instances related to the WQL event filter associated with the MSFT_ForwardingConsumer instance. In both cases, the most important property is the StatusCode property (line 37), since this value contains a return code determining if the event forwarding was successful (see Table 3.83).

Table 3.83: The StatusCode Property Returned Values

Value

Description

WMIMSG_E_AUTHFAILURE

0x80042101

There was a problem in attaching authentication info with the forwarded event.

WMIMSG_E_ENCRYPTFAILURE

0x80042102

There was a problem in encrypting the forwarded event.

WMIMSG_E_INVALIDADDRESS

0x80042105

The target address specified for the forwarded event is invalid.

WMIMSG_E_TARGETNOTFOUND

0x80042106

The machine for the specified target address was not found.

WMIMSG_E_INVALIDMESSAGE

0x80042108

A receiver has received an invalid / corrupt message.

WMIMSG_E_REQSVCNOTAVAIL

0x80042109

A requested service is not available.

WMIMSG_E_TARGETNOTLISTENING

0x80042113

The target is valid but it is not listening for forwarded events.

3.9.3 The Event Correlator providers

The Event Correlator providers are available under Windows XP. The goal of this provider set is to correlate different events and send an alert or provide information only if a sequence of WMI events or a combination of an expected WMI data set is available from the system. For instance, monitoring a system and sending an alert only when the disk usage is at 50 percent and when the CPU usage has been higher than 80 percent in the last ten minutes for a period of two minutes is an example of correlation.

Although available in Windows XP, it is very important to note that today Microsoft does not encourage the use of these WMI correlation providers. This is the reason why Microsoft doesn't plan to make this provider available under Windows Server 2003 (although it was available during the beta program of Windows Server 2003).

Actually, Microsoft does not recommend any time and development investment in this feature due to the complexity of the current correlation implementation and some upcoming architectural changes regarding the future of the Windows management. Microsoft does not plan to enhance and support these WMI providers in the future and plans to provide a new correlation architecture, which will be .NET based with the next version of its operating system. You can check Chapter 5, section 5.8, "A Look into the Future of WMI Scripting," for a view of the WMI Scripting future.

Therefore, we will not cover these providers and their related classes. However, since it is available in Windows XP, for greater details it is recommended that you refer to the platform SDK. For your information, Table 3.84 contains the list of correlation providers with their related classes as is right after installation.

Table 3.84: The Correlation WMI Providers

Provider Name

Provider Name Space

Class Provider

Instance Provider

Method Provider

Property Provider

Event Provider

Event Consumer Provider

Support Get

Support Put

Support Enumeration

Support Delete

Windows Server 2003

Windows XP

Windows 2000 Server

Windows 2000 Professional

Windows NT 4.0

The Updating consumers

Microsoft WMI Updating Consumer Assoc Provider

Root/subscription

X

X

X

X

X

X

  • MSFT_UCScenarioAssociadon

Microsoft WMI Updating Consumer Event Provider

Root/subscription

X

X

  • Select * From MSFT_UCTraceEventBase

  • Select* From MSFT_UCEventBase

Microsoft WMI Updating Consumer Provider

Root/subscription

X

X

  • MSFT_Updatingconsumer

  • MSFT_UCScenarioControl

The Template providers

Microsoft WMI Template Association Provider

Root/subscription

X

X

X

X

Microsoft WMI Template Event Provider

Root/subscription

X

X

  • Select * From_InstanceOperationEvent WHERE TargetInstance ISA "MSF_TemplateBase"

Microsoft WMI Template Provider

Root/subscription

X

X

X

X

X

X

The Transient providers

Microsoft WMI Transient Event Provider

Root/subscription

X

X

  • Select * From MSFT_TransientEggTimerEvent

  • Select * From_InstanceOperationEvent where TargetInstance isa "MSFT_TransientStateBase"

Microsoft WMI Transient Provider

Root/subscription

X

X

X

X

X

X

Microsoft WMI Transient Reboot Event Provider

Root/subscription

X

X

  • Select * From MSFT_TransientRebootEvent




Leveraging WMI Scripting
Leveraging WMI Scripting: Using Windows Management Instrumentation to Solve Windows Management Problems (HP Technologies)
ISBN: 1555582990
EAN: 2147483647
Year: 2003
Pages: 82
Authors: Alain Lissoir

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net