Windows Management Infrastructure Blog

WMI: Improving your WMI application performance in fan-out scenario

One of the powerful capabilities in WMI is allowing authenticated users and applications to perform management tasks on a remote computer through DCOM. This is particularly useful in the fan-out scenario where developers can write applications to monitor a group of workstations and servers from a single machine using WMI.

For example, a developer who wants to write an application to collect the free disk space on all computers in an organization can use one of the WMI client APIs – WMI COM API, System.Management in .NET, WMI Scripting API, or WMI PowerShell cmdlets – to collect the information from all the machines. Among these four client APIs, WMI COM API offers developers the greatest control of the way a WMI remote connection is established and closed.

In this blog, I will talk about three different ways of connecting to a remote machine using WMI to perform multiple WMI operations, and their performance differences. Suppose I have ten machines and I need to periodically poll the status of the hard drives on each machine using WMI. I can choose one of the following approaches to write my application:

1)   Connecting using Explicit Credential

My application calls IWbemLocator::ConnectServer method to establish a DCOM connection with each remote machine using an explicit credential I specified. The credential could be the local administrator of the remote machine. The application polls the hard drive status through a WMI provider and then closes the connection. The connect-poll-close process is repeated continuously to get the fresh status from all remote machines.

2)     Connecting using Default Credential

Like (1) above, my application connects to each remote machine, polls the hard drive status through a WMI provider, and closes the connection.  The only difference in this approach is that no explicit credentials are specified when calling the ConnectServer method. The application uses the default credential, which could be a domain user that has administrative access to the remote machines.

3)     Reusing WMI Connection

My application calls the ConnectServer method to connect to the remote machines either with explicit credential or default credential specified, and then it polls the status of the hard drives through a WMI provider. Instead of closing the connection, my application keeps it open for subsequent polls by holding on to the reference to the IWbemServices object.

Let’s find out what the differences are for these three scenarios in terms of WMI throughput ^[1]. I set up ten machines with a variety of Windows OS installed. Each machine is joined to the same domain and has the same hardware configuration ^[2]. Instead of polling the hard drive status, my WMI application repeatedly connects to each of the ten machines, and performs the same WMI object query operation on a test WMI provider. To minimize the variation due to the provider processing time, my test WMI provider always returns the same set of results for the query I use on any given machine. Figure 1 shows the average throughput of the client-side OS platforms on which my WMI application is run. 

Figure 1: Fan out Remoting Throughput using WMI

Of course the absolute values of the throughput may vary depending on different factors, such as the payload of the query results, the network latency, the processor speed, etc. However, there are a couple of interesting observations in this fan-out experiment:

a)      Of all three client-side OS platforms I tested, if my application uses the same WMI connection throughout the life time of the WMI operations (which is approach 3 mentioned above), the throughput measured is almost 3 times greater than if the application opens and closes the connection for each WMI operation. This is due to fewer authentication requests that the client-side OS needs to process.

b)      On Windows Server 2008 only, my WMI application using default credential has throughput nearly 6 times higher compared to my application using explicit credential. Moreover, the lsass.exe process consumes considerable CPU cycles when connecting to the remote machines using explicit credential. The performance delta is partly due to a security change made in Windows Vista and Windows Server 2008.

c)       On Windows Server 2008 with explicit credential, I am able to improve the throughput of my application to the level comparable to the throughput on the other two client-side OS platforms by changing the way I pass the explicit credential to my test code. Here is the pseudo-code of my change:

1.       Call LogonUser function with an explicit credential

2.       Call ImpersonateLoggedOnUser function with the token returned in (1)

3.       Call ConnectServer to connect to remote machines using default credential

4.       Perform the WMI object query

5.       Close the connection

        Best of all, the change keeps the lsass.exe process running like cool mint.

Andy Cheung [MSFT]

PS: Thanks to Vivek and Sunil for the help on this post.

^[1] The unit of measurement for throughput I use in this blog is operation per second. An operation consists of connecting to a remote server, querying WMI objects, parsing the result set, and closing the connection. In the “Reusing WMI Connection” approach, the cost of establishing and closing a connection is incurred only once.

^[2] All machines are Pentium 4, 2.4GHz, 1GB RAM. The network is Gigabit. All client-side OS platforms are 64-bit.

Writing WMI provider in a day

Writing WMI provider in native code has steep learning curve. It involves writing MOF files and implementing methods from IWbemServices and IWbemProviderInit interfaces. Sometimes it becomes difficult and time consuming to debug issues in the WMI provider.

WMI.Net Provider Extension 2.0 was first introduced in Visual studio 2008 and is part of .Net Framework 3.5. It is based on the attribution model where MOF files are generated automatically and developers doesn’t have to implement any of the methods from the IWbemProviderInit or IWbemServices interfaces. Attributes can be added at the assembly, class, properties or method levels to specify what part of the managed application exposes WMI functionality. WMI.Net Provider Extension 2.0 generates MOF file and register it automatically based on the information provided in the attributes.

WMI.Net Provider Extensions 2.0 can be used to write both coupled providers and decoupled providers. There is a very good article on writing coupled providers here .

Writing WMI Providers in WMI.Net Provider extension 2.0 is fairly easy to write and debug. To give an idea I was able to write my own Win32_Process class with extended functionality in less than a day.

BITS FileTransfer cmdlets are now known as BitsTransfer cmdlets!

If you have been using BITS PowerShell cmdlets since the Windows 7 beta and are currently running the Windows 7 RC, then you will likely have had some trouble finding the BITS cmdlets in the RC.

Fear not, the BITS PowerShell cmdlets are now known as the BitsTransfer cmdlets. For updates, refer to http://blogs.msdn.com/wmi/archive/2009/01/23/introducing-bits-powershell-cmdlets.aspx

Among some of the cmdlet changes between beta and RC:

• The cmdlets module is now known as BitsTransfer
• The cmdlets have been renamed and they are now known as BitsTransfer cmdlets instead of FileTransfer cmdlets
• ServerFileName and ClientFileName parameters are now known as Source and Destination
• Support for relative paths and wildcard character when specifying file locations

- Alex Ng [MSFT]

WMI: REFERENCES OF query failure during Provider startup could be disastrous

Hello, my name is Venkatesh Ganga. I’m an Escalation Engineer on the Microsoft Platform Global Escalation Services team. In this blog I would like to talk about an interesting WMI issue I worked few months ago. The idea behind this blog is to discuss how WMI works under the hood. In this article I show a few call stacks but the focus of the article is really to point out WMI concepts.  

We had a customer who was getting "Provider cannot perform the requested operation" error for all WMI queries to any provider on some of his Windows XP machines.

Also the WMI Control (wmimgmt.msc) properties show the following:-

 Figure 1:

Moreover nothing happens when he clicks on any other tabs like Logging, Backup/Restore etc.  Running WMIDIAG showed “24 error(s) 0x80041024 - (WBEM_E_PROVIDER_NOT_CAPABLE) Provider cannot perform the requested operation“.

All the standard WMI troubleshooting was done before I was engaged like rebuilding the WMI repository, checking DCOM permissions etc. But nothing resolved the issue. We got the image of one of the problem machines to reproduce the problem locally. Initially I didn’t know where to start to debug the issue as there were multiple symptoms. I decided to trace the execution of  the inbox provider CIMWin32.dll  by issuing the WMI query “Select * from Win32_Processor” and find where it fails and to go from there.

WMI maintains each provider’s physical implementation information such as the CLSID of the provider’s COM object, the hosting model, etc in an instance of the __Win32Provider system class. Each provider can support one or more types mentioned below. Based on the type(s) the provider supports, WMI will create an instance of each supported type.

·         __ClassProviderRegistration

·         __EventConsumerProviderRegistration

·         __EventProvideRegistration

·         __InstanceProviderRegistration

·         __MethodProviderRegistration

·         __ObjectProviderRegistration

·         __PropertyProviderRegisration

For example, looking at the .mof file for the Cimwin32 provider we can quickly determine that the provider registers for 2 types, the Instance Provider and the Method Provider as Figure 2 displays.

Figure 2

Since our test query “select * from Win32_Processor” retrieves the instances of Win32_Processor class, WMI checks the CIMWin32’s __InstanceProviderRegistration object to see if  the SupportsEnumeration property is set. In debugging the customer’s image, I found that the  runtime object WMI maintains for CIMWin32 provider stated “False” for the SupportsEnumeration property.

WMI maintains an in-memory structure for each provider and fills that structure out with information from the repository.  The CreateInstanceEnumAsync checks the provider’s in-memory structure to determine whether it supports enumeration.  From my debug on the customer’s system the provider did not support enumeration.

In Memory at Runtime

0:003> kL

ChildEBP RetAddr

0091f560 77e7a1ac  wmiprvse!CInterceptor_IWbemSyncProvider::CreateInstanceEnumAsync+0x21

0091f588 77ef421a  rpcrt4!Invoke+0x30

0091f998 77ef4bf3  rpcrt4!NdrStubCall2+0x297

0091f9f0 756bd7fe  rpcrt4!CStdStubBuffer_Invoke+0xc6

0091fa04 77600c31  fastprox!CBaseStublet::Invoke+0x22

0091fa44 77600bdb  ole32!SyncStubInvoke+0x33

0091fa8c 7750f237  ole32!StubInvoke+0xa7

0091fb64 7750f15c  ole32!CCtxComChnl::ContextInvoke+0xe3

0091fb80 77600b11  ole32!MTAInvoke+0x1a

0091fbb0 776009bc  ole32!AppInvoke+0x9c

0091fc84 77600715  ole32!ComInvokeWithLockAndIPID+0x2e0

0091fcd0 77e79c75  ole32!ThreadInvoke+0x1cd

0091fd04 77e79bda  rpcrt4!DispatchToStubInC+0x38

0091fd58 77e79b06  rpcrt4!RPC_INTERFACE::DispatchToStubWorker+0x113

0091fd7c 77e89f9c  rpcrt4!RPC_INTERFACE::DispatchToStub+0x84

0091fdbc 77e89fdd  rpcrt4!RPC_INTERFACE::DispatchToStubWithObject+0xc0

0091fdfc 77e7be65  rpcrt4!LRPC_SCALL::DealWithRequestMessage+0x2cd

0091fe20 77e76794  rpcrt4!LRPC_ADDRESS::DealWithLRPCRequest+0x16d

0091ff80 00000000  rpcrt4!LRPC_ADDRESS::ReceiveLotsaCalls+0x28f

Repository

In contrast when we checked the customer’s system, we determined that the repository showed that the provider’s “SupportEnumeration” property was set to true.  Verification steps below:

1.       Run wbemtest and connect to root\cimv2

2.       Enter below query

select * from __InstanceProviderRegistration where provider="__Win32Provider.Name=\"CIMWin32\""

3.       You should get 1 object in the Query Result window. Double click it and look at the properties. On a working system you should notice that the SupportEnumeration property is set to “True” for the CimWin32 provider as Figure 3 shows.

Figure 3.

Discrepancy Between the In-Memory and Repository

Now we know WMI is not initializing the provider correctly as there is a discrepancy between the in-memory objects it maintains and the repository.

So I started debugging the CIMWin32 provider initialization where WMI fills the in-memory structure. During the provider initialization WMI makes a  REFERENCES OF query to get all the types CIMWin32 supports. On our customer’s machine this query yields 0 objects whereas on a working system it returns 2 objects (one for __InstanceProviderRegistration and other for __MethodProviderRegistration)

"references of {__Win32Provider.Name="CimWin32"}"

Figure 4. 

Here is the debug of how we found the exact “REFERENCES OF“query being issued.

0:007> kL

ChildEBP RetAddr 

0164fa38 59841a6c wbemcore!CWbemNamespace::ExecQuery

0164fa88 59841c41 wmiprvsd!CServerObject_ProviderRegistrationV1::QueryRepositoryUsingQuery+0x47

0164faac 59841d31 wmiprvsd!CServerObject_ProviderRegistrationV1::QueryRepository+0x42

0164fac8 5980f056 wmiprvsd!CServerObject_ProviderRegistrationV1::Load+0x33

0164fba8 762e9cfd wmiprvsd!CServerObject_BindingFactory::GetProvider+0x1f5

0164fc24 76301d1e wbemcore!CWbemNamespace::DynAux_ExecQueryExtendedAsync+0x81

0164fce0 76302912 wbemcore!CQueryEngine::ExecComplexQuery+0x1f4

0164fdec 763032bd wbemcore!CQueryEngine::ExecQlQuery+0x37

0164fe90 762fc769 wbemcore!CQueryEngine::ExecQuery+0x228

0164feac 762cef24 wbemcore!CAsyncReq_ExecQueryAsync::Execute+0x19

0164fed8 762ced4e wbemcore!CCoreQueue::pExecute+0x3c

0164ff08 762f25cb wbemcore!CCoreQueue::Execute+0x18

0164ff50 762cee89 wbemcore!CWbemQueue::Execute+0xf6

0164ff84 762cf055 wbemcore!CCoreQueue::ThreadMain+0x111

0164ffb4 7c80b683 wbemcore!CCoreQueue::_ThreadEntry+0x45

0164ffec 00000000 kernel32!BaseThreadStart+0x37

0:044> du 04f57424

04f57424  "references of {__Win32Provider.N"

04f57464  "ame="CIMWin32"}"

Repository driver (repdrvfs.dll) works on the above references query. The references query failed with error 80041017 (WBEM_E_INVALID_QUERY). It failed due to the apostrophe in the computer name. While parsing the query the repository driver considers anything between the apostrophes or quotes as a name. This apostrophe in the computer name misleads WMI to look for a closing apostrophe which is not there and hence the references query fails with error.


0:005> kL

ChildEBP RetAddr

05cbfec8 75214a74 repdrvfs!CNamespaceHandle::ExecReferencesQuery+0x1dd

05cbff88 75215518 repdrvfs!CNamespaceHandle::ExecQuerySink+0xc2

05cbffac 7520e11c repdrvfs!CExecQueryObject::Execute+0x28

05cbffb4 7c80b683 repdrvfs!A51FiberBase+0xd

05cbffec 7c82ffa9 kernel32!BaseThreadStart+0x37

05cbffec 00000000 kernel32!BaseFiberStart+0x17

0:005> du 00b56218
00b56218 "references of {\\COMPUTERNAME'User1"
00b56258 "\ROOT\cimv2:__Win32Provider.Name"
00b56298 "="CIMWin32"}"

0:005>r

WMI makes similar REFERENCES OF query for all the providers to get the types they support. But they all fail for same reason. Hence WMI queries to all the providers fail. We renamed the computer name without apostrophe and rebooted the box. Now WMI initializes properly and the WMI queries start working again. An apostrophe is not a valid character for the computer name. We never found out how the computer name got set with a apostrophe. If we try to set the computer name through GUI it throws error saying the computer name has invalid characters.  However, hopefully through this experience, you have a better understanding of how WMI implements providers to help you better troubleshoot your next WMI issue.

So in review here are the main takeaways from this blog:

1.       WMI maintains an instance of __Win32Provider system class for each provider.  Based on the provider’s registration (see .mof file above) it maintains one or more registration system classes such as __InstanceProviderRegistration.

2.       WMI uses the REFERENCES OF query to map the instance of __Win32Provider to the providers registration types (e.g. __InstanceProviderRegistration).

3.       To view the various providers registered on your system, connect to root\Cimv2 and issue the following query: “Select * from __Win32Provider”.

4.       And to get the types that each provider supports, issue the following query:

a.       references of {__Win32Provider.Name="<PROVIDER_NAME>"}

How To Use WSMan Proxy Support

The end user can operate a WSMan client from behind a web proxy for remote management, that is, the client machine connects to the internet through a web proxy server. All HTTP traffic between the client machine and the internet must pass through the proxy server.

Communication between WSMan client and server must remain secure to avoid eavesdropping by proxy, so WSMan proxy support is only over HTTPS, setting proxy information is not valid when the HTTP transport is specified. WSMan implements its own failover mechanism, WSMan client stack caches the result of the Winhttp auto-detection process per session for performance reasons.

In this blog, we illustrate the scenario of using WSMan client via web proxy for remote management.

1) On server machine

In the following example, we use either “quickconfig” to create a HTTPS listener and explicitly open port 5986, or set EnableCompatibilityHttpsListener to True to create a HTTPS listener and explicitly open port 443, We also make sure the server side allows Basic authentication

2) On client machine

After setting up the server side, end user can operate a WSMan client from behind a web proxy for remote management, please note most winrm-related PS cmdlets contain a SessionOption parameter which allows the proxy info to be specified

In the above example we create a WSMan Session option hashtable which can be passed into WSMan cmdlets such as Get-WSManInstance. That session option takes the following parameters and values related to proxy info:

ProxyAuthentication: This parameter takes a set of authentication methods the user can select from, Specifying the authentication method to use at the proxy. The available options should be as follows:

                Negotiate           Use Negotiate authentication (Either Kerberos or NTLM) for establishing a remote connection.

                Basic                      Use basic authentication for establishing a remote connection

                Digest                   Use Digest authentication for establishing a remote connection

ProxyCredential:

      required if ProxyAuthentication is Basic or Digest, opional if ProxyAuthentication is Negotiate as it can use the implicit logon credential

                cannot be specified if ProxyAuthentication is not specfied

ProxyAccessType            

                ProxyIEConfig

                ProxyWinHttpConfig

                ProxyAutoDetect

                ProxyNoProxyServer: Do not use a proxy server. All host names will be resolved locally

Is WMIprvse a real villain?

How often has it occurred that you were working on something and suddenly your computer became slow? You opened task manager to find out the culprit that is hogging your systems CPU cycles. You sorted the processes according to CPU usage and saw WMIprvse.exe happily sitting at the top.

Before putting the blame on WMIprvse.exe have you ever wondered that it can be that some other application contracted the WMIprvse.exe to create havoc on your computer? Here’s how you can find the culprit which is using WMIprvse.exe to eat up your system resources.

Open Event viewer (Control Panel\System and Security\Administrative Tools\Event Viewer) and enable “Show Analytic and Debug Logs”

Navigate to Application and Services Logs -> Microsoft -> Windows -> WMI-Activity

Right Click on WMI-Activity -> Trace and select Properties

Select “Enable Logging”

And now you are all set to trace the path culprit takes.

Let’s see how a typical event looks like and try to understand the various fields in the event

GroupOperationID: is a unique identifier that is used for all events reported for a specific client.

OperationId: indicates the operation sequence.

Operation: This will give you the WMI query issued by the client application. In the above example, CreateInstanceEnum has been issued on the win32_process class.

ClientMachine: Computer name from which the request originated.

User: indicates the account that makes a request to WMI by running a script or through CIM Studio.

ClientProcessId: Process Identifier for the process which issued the WMI query.

NamespaceName: shows the WMI namespace to which the connection is made

(Visit http://msdn.microsoft.com/en-us/library/aa826686(VS.85).aspx for detailed information.)

A quick look up in the task manager for the ClientProcessId will give you the process name against which you might want to take action to bring your computer back to the normal state.

Hope this will help in finding the real villain!!

Varun Singh

MSFT

FAQ for security enhancements posted on 05/19

 This post covers some FAQs on the WMI changes detailed here on 5/19 and is intended to address common questions that might arise about the two new running modes for the WMI provider host process.

Question: How to identify if the WMI provider used by our product is launched in secure mode or not?

Answer:  Check the registry values under the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\CIMOM\SecuredHostProviders.

If your provider is present in this registry hive, it will be launched in a secure mode

Question: How to control the behavior of registry keys when I’m doing a deployment in an enterprise?

·        Answer: Review the following MSDN topic for setting registry keys through GP: Registry Keys for Controlling Provider Security

Question: How to control the behavior of single provider, which my product uses? I also want to move it to the secure mode?

Answer: Check the registry values under the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\CIMOM\SecuredHostProviders.

And add your provider the registry key in the following format:

<Namespace>:__Win32Provider.Name=”<ProviderName>” REG_SZ            0

(Either __win32provider or the provider Class derived from __win32provider)

Example provider names:

Question: After I move my provider to secure mode, my application/product quits working. What should I do?

Answer: Move your provider back to compatibility mode. Then you should contact the company which has written the WMI provider for you. As a workaround, you can add your provider to the following registry key:

HKLM \SOFTWARE\Microsoft\WBEM\CIMOM\CompatibleHostProviders

Question: How do I verify the WMI provider used by our product is launched in secure mode?

Answer:  Use the following steps to verify if your provider is launched in secure mode:

1)      Log on to a computer that has your product installed as an Administrator.

2)      Download & Install ProcExplorer  tool.

3)      Run the ProcExplorer as administrator.

4)      Open the LowerPane view by selecting View -> Lower Pane View -> Handles ( or use CTRL + H)

5)      Using Task Manager identify and Kill all ‘wmiprvse.exe’ processes running under the context of Network Service or Local Service

6)      Execute a test case for your application that exercises a WMI Query using a specific WMI Provider.

7)      This will create a new WMIPrvSE.exe process to service the new WMI Query that you just executed.

8)      On the process explorer tool bar ensure that you have selected the View DLLs as shown in the figure below.

9)      Look in the lower pane to see if your DLL has been loaded in the newly created WMIPrvSE.exe

10)   Double click on the WMIPrvSE.exe to open up the Properties dialog box

11)   Select the ‘Security’ Tab and make sure the following

a.      Log on SID is of the form (S-1-5-5-****)

b.      The log on SID is also marked as the owner

12)   Click on the permission button and verify that neither NetworkService nor LocalServices come up in the list. This will confirm that your provider is now being launched in secured mode.

Question: I’m having compatibility issues with my provider in secure mode. I want to move the provider from secure mode to compatible mode. What should I do?

Answer:  You should delete the provider entry that is listed under the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\CIMOM\SecuredHostProviders.

Then add your provider to the following registry key:
HKLM \SOFTWARE\Microsoft\WBEM\CIMOM\CompatibleHostProviders.

WMI Feature Announcement

Changes were made to Windows platforms to help provide more security for the WMI provider host process (wmiprvse.exe).  These changes introduce three new group policies and two running modes for the WMI shared host, which are called secure and compatible.

These new registry keys and host provider running modes are also available for computers running Windows XP SP2 and later, all versions of Windows Server 2003, Windows Vista, and Windows Server 2008.  If you are running Windows Update, this feature should be installed automatically. 

For more information, click on the following links:

·         Registry Keys for Controlling Provider Security

·         KB 959454

·         Microsoft Security Bulletin MS09-012

Association Traversal Using WSMan cmdlets

First let us review the concept of “CIM/WMI association”, then we’ll show examples on how to perform association traversal using WSMan-related cmdlets. Please note this is a generic discussion about association traversal but targeting Win7 implementation. Applying them to standard interop namespace and discovering DMTF profiles and associated instances targeting 3^rd party implementation will be discussed later in detail in a separate blog.

In this blog, we discuss three topics:

•              Concept of “CIM/WMI association”

•              Associated instance traversal

•              Association instance traversal

1) Concept of “CIM/WMI association”

An association in CIM/WMI describes a relationship between two or more classes. Every association is represented by a CIM/WMI association class that contains two or more references. The CIM uses "association" to link different parts of the enterprise model together. WMI also supports associations.

Taking the example of services on windows. Win32_Service WMI class represents a service on a computer system running Windows. Win32_ComputerSystem WMI class represents a computer system. A windows service is part of a computer system, this relationship is defined by the association class Win32_SystemServices which relates a computer system and a service program that exists on the system. A windows service may have several dependencies on other services, eg., WinRM service cannot start up unless both RpcSs and HTTP services start up. This dependency is defined by an association class Win32_DependentService which relates two interdependent services.

Win32_ComputerSystem?Name=MachineName

                                |

                                |              Win32_SystemServices

                                |

Win32_Service?Name=winrm

                                |

                                |              class Win32_DependentService

                                |              {

                                |                Win32_BaseService ref Antecedent;

                                |                Win32_BaseService ref Dependent;

                                |              };

                                |

Win32_Service?Name=RpcSs

2) Associated instance traversal

Here we want to retrieve instances that are associated with a particular source instance (rather than the intervening association instances). In the above diagram, the starting source instance is “Win32_Service?Name=winrm”, associated instance traversal will retrieve  target instance “Win32_Service?Name=RpcSs”. The instances that are retrieved are referred to as the endpoints. Each endpoint is returned as many times as there are associations between it and the source object

The basic syntax for associated instance traversal using WSMan cmdlets is

Get-WSManInstance -Enumerate -ResourceURI <Uri> -Dialect <Uri> -filter <string> ……

Where filter string has the following format

{Object=EPR [;AssociationClassName=AssocClassName][;ResultClassName=ClassName]

[;Role=RefPropertyName][;ResultRole=RefPropertyName]}

Note: The filters enclosed in [] are optional. For example

•              Object: the source object is represented by an EPR such as “Win32_Service?Name=WinRM”. It is imperative to provide an EPR(Object) at a minimum to be able to retrieve associated instances, all others are optional and they’re used to narrow down on the associated instances.

•              AssociationClassName: Name of an association class such as “Win32_DependentService”. Specifying this qualifier implies a request for associated instances of a source Object which are associated to each other through this association class. The returned endpoints must be associated with the source through the specified class or one of its derived classes.

•              ResultClassName: Name of a CIM/WMI class (not an association) such as “Win32_Service”. Specifying this qualifier implies a request for associated class instances of (or derived from) ResultClassName which are associated to a source Object. The returned endpoints associated with the source object must belong to or be derived from the specified class.

•              Role: Name of a reference property defined in the association class such as “dependent”. Specifying this qualifier implies a request for associated instances that participate in an association where source Object plays this Role. In the above example, WinRM service is dependent on RpcSs service

•              ResultRole: Name of a reference property defined in the association class such as “antecedent”. Specifying this qualifier implies a request for associated instances that play this ResultRole in their association with the source Object. In the above example RpcSs service is antecedent so it must be started first before dependent WinRM service can be started

3) Association instance traversal

Here we want to retrieve all association instances that refer to a particular source instance (rather than the associated endpoints). In the above diagram, the starting source instance is “Win32_Service?Name=winrm”, association instance traversal will retrieve  instances “Win32_DependentService”. The instances that are retrieved are the intervening association instances

The basic syntax for association instance traversal using WSMan cmdlets is

Get-WSManInstance -Enumerate -ResourceURI <Uri> -Dialect <Uri>

-Associations -filter <string> ……

Where filter string has the following format

{Object=EPR[;ResultClassName=ClassName][;Role=RefPropertyName]}

Note: The filters enclosed in [] are optional. -Associations indicate retrieval of association instances as opposed to associated instances. For example

•              Object: the source object is represented by an EPR such as “Win32_Service?Name=WinRM”. It is imperative to provide an EPR(Object) at a minimum to be able to retrieve association instances, all others are optional and they’re used to narrow down on the association instances.

•              ResultClassName: Name of the CIM/WMI association class such as Win32_DependentService. Specifying this qualifier implies a request for association class instances of (or derived from) ResultClassName for a source Object. The returned association objects must belong to or be derived from the specified class

•              Role: Name of a reference property defined in the association class such as “dependent”. Specifying this qualifier implies a request for those association instances where the source Object plays this Role in the association. In the above example, WinRM service is dependent on some other services

Example: Directory backup with BITS cmdlets

UPDATE: This posting has been updated with a script that is based on the Win7 RC version of the BITS PowerShell cmdlets.

-----

 Here we have a sample PowerShell script for copying a directory to another UNC path. What's so special about this, you say? This scripts uses BITS PowerShell cmdlets; which means that you can backup a folder to a network location while preserving the responsiveness of other network apps.

This example is based on the Win7 beta RC version of the BITS Powershell cmdlets.

How to Use: 

1. Load this script by running: Import-Module <location of script>\bitsbackup.ps1
2. Usage example: Backup-Directory .\myfolder \\backupserver\sharename -recurse
   • This will create a copy of myfolder under \\backupserver\sharename\myfolder
3. For more help: Get-Help Backup-Directory

Alex Ng [MSFT]

Forwarding security related events from XP, Win2k3, Vista using WinRM (WSMan) event forwarding

Procedure for forwarding system and application logs from a given winrm endpoint can be found at http://blogs.technet.com/otto/default.aspx 

In order to forward security events, the following needs to be done at the endpoint:

If endpoint is Vista, WS08: Add "Network Service" to the "Event Log Readers" group. This is because limited users have access to read events from the security log - "Event Log Readers" group being one of them.

If endpoint is Win2k3 R2: The following CustomSD key needs to be set within "HKLM/SYSTEM/CCS/Services/EventLog/Security" to "O:BAG:SYD:(A;;CC;;;NS)". This is because on Win2k3 there is no event log readers group. More info can be found at http://support.microsoft.com/kb/323076

If endpoint is XP SP2+: WinRM service needs to be running as LocalSystem

Searching for WMI classes

Working with WMI can be difficult if I don’t know what I am looking for exactly. Most of the time I know the management entity I am interested in but not the WMI class that can provide this management information.

It is easy to discover the classes in powershell V2 knowing just the management entity.

I am interested in knowing about the disks on my machine but don’t seem to remember the class.

I know that all the classes start with “win32_”.

Get-WMIObject –List –namespace “root” –class “win32_*disk*”

No luck so far.

May be it is not in the root namespace. How do I figure out which namespace can provide this information?

PS C:\Windows\System32> Get-WMIObject -List -namespace "root" -class "win32_*disk*" -recurse

   NameSpace: ROOT\CIMV2

Name                                Methods              Properties

----                                -------              ----------

Win32_LogicalDisk                   {SetPowerState, R... {Access, Availability, BlockSize, Caption...}

Win32_MappedLogicalDisk             {SetPowerState, R... {Access, Availability, BlockSize, Caption...}

Win32_DiskPartition                 {SetPowerState, R... {Access, Availability, BlockSize, Bootable...}

Win32_DiskDrive                     {SetPowerState, R... {Availability, BytesPerSector, Capabilities, CapabilityDesc...

Win32_LogicalDiskRootDirectory      {}                   {GroupComponent, PartComponent}

Win32_DiskQuota                     {}                   {DiskSpaceUsed, Limit, QuotaVolume, Status...}

Win32_LogonSessionMappedDisk        {}                   {Antecedent, Dependent}

Win32_LogicalDiskToPartition        {}                   {Antecedent, Dependent, EndingAddress, StartingAddress}

Win32_DiskDrivePhysicalMedia        {}                   {Antecedent, Dependent}

Win32_DiskDriveToDiskPartition      {}                   {Antecedent, Dependent}

Win32_PerfFormattedData_PerfDisk... {}                   {AvgDiskBytesPerRead, AvgDiskBytesPerTransfer, AvgDiskBytes...

Win32_PerfRawData_PerfDisk_Logic... {}                   {AvgDiskBytesPerRead, AvgDiskBytesPerRead_Base, AvgDiskByte...

Win32_PerfFormattedData_PerfDisk... {}                   {AvgDiskBytesPerRead, AvgDiskBytesPerTransfer, AvgDiskBytes...

Win32_PerfRawData_PerfDisk_Physi... {}                   {AvgDiskBytesPerRead, AvgDiskBytesPerRead_Base, AvgDiskByte...

Here it goes. Of course it is disk drives I am interested in and most appropriate class seems to be Win32_DiskDrive. How would I confirm if it is the same class I was interested in?

Let us check the description of this class.

$c = gwmi -query " select * from meta_class where __class='win32_diskdrive'" –amended

$c.psbase.Qualifiers["Description"].Value

The Win32_DiskDrive class represents a physical disk drive as seen by a computer running the Win32 operating system.

Any interface to a Win32 physical disk drive is a descendent (or member) of this class.

The features of the disk drive seen through this object correspond to the logical and management characteristics of the drive.

In some cases, this may not reflect the actual physical characteristics of the device. Any object based on another logical device would not be amember of this class.

Example: IDE Fixed Disk.

That is a hit.

Nitin Gupta [MSFT]

WSMan Enhancements in PowerShell 2.0

Windows PowerShell 2.0 makes it easy to retrieve WSMan specific Management information in an intuitive, discoverable and script friendly manner.

Variety of tasks such as configuring a machine for remote management to connecting to WinRM service on a machine and managing resources both in-band and out-of-band can be performed.

Available WSMan specific cmdlets can be categorized in two buckets:

·         Cmdlets for Performing WSMan Operations:

o   Test-WSMan

o   Get-WSManInstance

o   Set-WSManInstance

o   New-WSManInstance

o   Remove-WSManInstance

o   Invoke-WSManAction

·         Cmdlets for Configuring WSMan Session:

o   Connect-WSMan

o   Disconnect-WSMan

o   New-WSManSessionOption

o   Set-WSManQuickConfig

o   Get-WSManCredSSP

o   Enable-WSManCredSSP

o   Disable-WSManCredSSP

Running "help *wsman*" in PowerShell 2.0 console provides a list of WSMan PowerShell Cmdlets.

Detail help, documentation and examples can be obtained by running "help <cmdlet name>".

Here is more detail information, including examples:

Test-WSMan

 Tests whether the WinRM service is running on a local or remote computer.

 The cmdlet submits an identification request that determines whether the WinRM service is running on a local or remote computer.  If the tested computer is running the service, the cmdlet displays the WS-Management identity schema, the protocol version,  the product vendor, and the product version of the tested service.

C:\PS>test-wsman -computername server01 -authentication default

wsmid           : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd

ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd

ProductVendor   : Microsoft Corporation

ProductVersion  : OS: 6.1.7021 SP: 0.0 Stack: 2.0

-----------

This command tests to see if the WinRM service is running on the computer named server01 using the authentication parameter.

Using the authentication parameter allows the Test-WSMan cmdlet to return the operating system version.

Get-WSManInstance

Displays management information for a resource instance specified by a Resource URI.

The cmdlet retrieves an instance of a management resource that is specified by a resource URI.

The information that is retrieved can be a complex XML information set  (an object) or a simple value.

This cmdlet is the equivalent to the standard WS-Management Get command.

This cmdlet uses the WSMan connection/transport layer to retrieve information.

    C:\PS>Get-WSManInstance -Enumerate wmicimv2/* -filter "select * from win32_service where StartMode = 'Auto' and State = 'Stopped'" -computername server01

    xsi                     : http://www.w3.org/2001/XMLSchema-instance

    p                       : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service

    cim                     : http://schemas.dmtf.org/wbem/wscim/1/common

    type                    : p:Win32_Service_Type

    lang                    : en-US

    AcceptPause             : false

    AcceptStop              : false

    Caption                 : Windows Media Center Service Launcher

    CheckPoint              : 0

    CreationClassName       : Win32_Service

    Description             : Starts Windows Media Center Scheduler and Windows Media Center Receiver services at startup if TV is enabled within Windows Media Center.

    DesktopInteract         : false

    DisplayName             : Windows Media Center Service Launcher

    ErrorControl            : Ignore

  -----------

    This command lists all of the services that meet the following criteria on the remote server01 computer:

       - The startup type of the service is "Automatic".

       - The service is stopped.

Set-WSManInstance

Modifies the management information that is related to a resource.

 C:\PS>set-wsmaninstance -resourceuri winrm/config -valueset @{maxenvelopsizekb=200}

     -----------

    This command modifies a WS-Management configuration property "maxenvelopsizekb" on a machine.

New-WSManInstance

 This cmdlet creates a new instance of a management resource.

 It uses a resource URI and a value set or input file to create the new instance of the management resource.

C:\PS>New-WSManInstance winrm/config/Listener -SelectorSet @{Transport=HTTPS} -ValueSet @{Hostname="HOST";CertificateThumbprint="XXXXXXXXXX"}

    -----------

    This command creates an instance of a WinRM HTTPS listener on all IP addresses.

Remove-WSManInstance

The Remove-WSManInstance deletes an instance of a management resource that is specified in the ResourceURI and SelectorSet parameters.

C:\PS>Remove-WSManInstance   winrm/config/Listener   -SelectorSet Address=test.Server.com;Transport=http

   -----------

  Delete the http listener on a remote machine.

Invoke-WSManAction

Invokes an action on the object that is specified by the Resource URI and by the selectors
(parameters specified by key value pairs)

    C:\PS>invoke-wsmanaction -action create -resourceuri wmicimv2/win32_process -valueset @{commandline="notepad.exe";currentdirectory="C:\"}

    xsi         : http://www.w3.org/2001/XMLSchema-instance

    p           : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Process

    cim         : http://schemas.dmtf.org/wbem/wscim/1/common

    lang        : en-US

    ProcessId   : 6356

    ReturnValue : 0

    -----------

 This command calls the Create method of the Win32_Process class. It passes the method two parameter values,   Notepad.exe and "C:\". As a result, a new process is created to run Notepad, and the current directory of the new process is set to "C:\".

Connect-WSMan

 The Connect-WSMan cmdlet connects to the WinRM service on a remote computer, and it establishes a persistent connection to the remote computer. You can use this cmdlet within the context of the WSMan provider to connect to the WinRM service on a remote computer.

However, you can also use this cmdlet to connect to the WinRM service on a remote computer before you change to the WSMan provider. The remote computer will appear in the root directory of the WSMan provider.

C:\PS>Connect-WSMan -computer server01

PS C:\Users\testuser> cd wsman:

PS WSMan:\>

PS WSMan:\> dir

   WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan

ComputerName                                  Type

------------                                  ----

localhost                                     Container

server01                                      Container

-----------

This command creates a connection to the remote server01 computer.

The Connect-WSMan cmdlet is generally used within the context of the WSMan provider to connect to a remote computer, inthis case the server01 computer. However, you can use the cmdlet to establish connections to remote computers before you change to the WSMan provider. Those connections will appear in the ComputerName list.

Disconnect-WSMan

The Disconnect-WSMan cmdlet disconnects the client from the WinRM service on a remote computer.

If you saved the WSMan session in a variable, the session object remains in the variable, but the state of the WSMan session  is "Closed". You can use this cmdlet within the context of the WSMan provider to disconnect the client from the WinRM service  on a remote computer. However, you can also use this cmdlet to disconnect from the WinRM service on remote computers  before you change to the WSMan provider.

    C:\PS>Disconnect-WSMan -computer server01

    C:\PS> cd WSMan:

    PS WSMan:\>

    PS WSMan:\> dir

       WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan

    ComputerName                                  Type

    ------------                                  ----

    localhost                                     Container

    -----------

This command deletes the connection to the remote server01 computer.

New-WSManSessionOption

 This cmdlet can be used to configure session specifc WSMan settings.

An example would be to provide one set of credentials to a proxy or gateway and another to the endpoint to which a connection is being established

New-WSManSessionOption -ProxyAuthentication Basic -ProxyPassword abc123 -ProxyUserName SomeUser -UseIEProxyconfig

Set-WSManQuickConfig

The Set-WSManQuickConfig cmdlet configures the computer to receive PowerShell remote commands that are sent by using WSMan

    The cmdlet performs the following:

    1. Checks whether the WinRM service is running. If the WinRM service is not running, the service is started.

    2. Sets the WinRM service startup type to automatic.

    3. Creates a listener to accept requests on any IP address. By default, the transport is HTTP.

    4. Enables a firewall exception for WSMan traffic .

  Run the cmdlet in an elevated console for Vista/Windows Server 2008 and later versions of Windows

    C:\PS>Set-WSManQuickConfig

    -----------

    This command sets the required configuration to enable remote management of the local computer.

    By default, this command creates a WinRM listener on HTTP.

CredSSP Related Cmdlets:

Get-WSManCredSSP

Enable-WSManCredSSP

Disable-WSManCredSSP

These cmdlets are used to Get/Enable/Disable Credential Security Service Provider-related configuration on the client/Server

This type of authentication is designed for commands that create a remote session from within another remote session.

For example, you use this type of authentication if you want to run a background job on a remote computer.

One point of Caution: CredSSP authentication delegates the user's credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials  are passed to it, the credentials can be used to control the network session.

Examples:

C:\PS>get-wsmancredssp

This command displays CredSSP configuration information for both the client and server.

The output identifies that this computer is or is not configured for CredSSP.

This is the output, if the computer is configured for CredSSP.

The machine is configured to allow delegating fresh credentials to the following target(s): wsman/server02.accounting.company.com

This is the output, if the computer is not configured for CredSSP.

The machine is not configured to allow delgating fresh credentials.

C:\PS>enable-wsmancredssp -role client -delegatecomputer *.accounting.company.com

   cfg         : http://schemas.microsoft.com/wbem/wsman/1/config/client/auth

   lang        : en-US

   Basic       : true

   Digest      : true

   Kerberos    : true

   Negotiate   : true

   Certificate : true

   CredSSP     : true

   -----------

This command allows the client credentials to be delegated to all the computers in the accounting.company.com domain.

    C:\PS>Disable-WSManCredSSP -Role Server

    This command disables CredSSP on the server, which prevents delegation from clients.

-Raghu Shantha [MSFT]

How to use WSMan config provider for certificate authentication

WSMan Client certificate authentication is primarily used in non-domain cases: client can specify certain certificate as credential, after authentication each other, it’s mapped to a local account on the server, meaning the WinRM service runs under the context of the mapped account when processing the request. When using client certificates, multiple client certificates can be mapped to a single account using pattern matching rules

In this blog, we discuss three topics:

•              Enable config settings for certificate auth

•              Configure cert mapping entry on the server machine

•              Perform remote operation using certificate auth on the client machine

1) Enable config settings for certificate auth

There’re specific config settings that control whether WinRM client and service will support Certificate Based Authentication

1.a) Client stack support for certificate auth is enabled by default, so you don’t need to change it if Certificate Based Authentication is desired

1.b) Service support for certificate auth is disabled by default to reduce attack surface, so you’ll have to explicitly enable it if Certificate Based Authentication is desired

2) Configure cert mapping entry

There are no entries in the certificate mapping table by default, but you can use certificate mapping resource URI "http://schemas.microsoft.com/wbem/wsman/1/config/service/certmapping" to perform get, put, create, delete, and enumerate operations using WSMan-related PS cmdlet such as “Get-WSManInstance, Set-WSManInstance, New-WSManInstance, Remove-WSManInstance”, but here in this blog I show examples using WSMan config provider instead as demonstrated by the following traversal.

Before configuring cert mapping entries on the server machine, let’s look at some of the key properties in the cert mapping entry

•              Subject : it’s the Subject field or Subject Alternative Name (SAN) field of client certificate, which contains the name of the entity that the certificate was issued to, first “*” character could match anything. For example:

o             If the certificate is issued to a user: then it contains the username in the form “Principal Name=user@domain.com”

o             If the certificate is issued to a machine: then it contains the name of the machine in the form “DNS Name=machine.foo.com”

•              Issuer: it’s the certificate thumbprint of the CA that issued the certificate. The certificate identified by the thumbprint must be present in the server machine “CA” store. The certificate must have key usage that allows it to sign other certificates (CERT_KEY_CERT_SIGN_KEY_USAGE), unless it’s a self-signed certificate in which case the key usage is not required

•              URI: it’s the URI or URI prefix for which this cert mapping will apply, last “*” character could match anything

2.1) Create cert mapping entry if the entry does not already exist, following PS script automates this process: first find user certificate which has the usage “Client Authentication (1.3.6.1.5.5.7.3.2)” as this is required for subsequent client cert auth; then get ISSUER name for the above user certificate, get the ISSUER thumbprint, which was used in the last line to create cert mapping entry, so remote access to WinRM using client certificates is mapped to user “certAdminAccount1” on the server machine. Please note if this local user is not in “administrators” group, you need to configure security to allow non-admin through but this is out of the scope of this blog, We’ll discuss “How to configure security for different URI” in a separate blog.

Output is similar to the following

2.2) Get cert mapping entry with specific keys if the entry exists

2.3) change any non-keys of cert mapping entry if the entry already exists [The Issuer, Subject, and URI properties are keys for the purposes of WS-Transfer operations.]

2.4) Enumerate will list all existing cert mapping entries

2.5) Delete cert mapping entry if the entry exists

3) Perform remote operation using certificate auth on the client machine

In the above first step, you enable both client and server config settings for certificate auth. In the second step, you configure cert mapping entry on the server machine that defines the actual mapping behavior. So here’s the final step on how to perform remote operation using certificate auth. These demo scripts in this blog may need to be changed a little bit to make it work for yourself such as valid URI, valid server name etc…

3.1) On the server machine you must have https listener and port is opened for through traffic, as client certificate authentication is allowed only when connecting to a https address.

3.2) On the client machine, following PS script demonstrates the process to perform a remote GET operation using certificate auth: first find user certificate which has the usage “Client Authentication (1.3.6.1.5.5.7.3.2)” as this is required for client cert auth; its thumbprint was used in the last line as the client credential

Three ways to configure WinRM listeners.

Configure WinRM Listeners through Quick Configure.

1.      Configuration HTTP listener and other actions to enable this machine for remote management:

winrm qc

2.      Configuration HTTPS listener and other actions to enable this machine for remote management:

winrm qc –transport:https

Note: this command requires a valid server authentication certificate present in machine MY store.

Configure WinRM HTTP listener through Group Policy.

1.      Launch Group Policy Management on Windows Server 2008 Domain Controller machine.

2.      Create a new Starter GPO.

a.      Right click “Starter GPOs” and click “New” and give a name (for example “turn on winrm http listener”) and comment if needed.

b.      Right click the created Starter GPO and click “Edit”. A window “Group Policy Starter GPO Editor” pops up.

c.      Browse the tree on left pane of “Group Policy Starter GPO Editor” to “Administrative Templatesà Windows ComponentsàWindows Remote Management (WinRM) à WinRM Service”

d.      Double click the policy setting “Allow automatic configuration of listeners”. A window “Allow automatic configuration of listeners” will show up.

e.      Check “Enabled” button. In the options field, put filter for IPv4 and IPv6. For example, fill “*” in both IPv4 and IPv6 text boxes and click OK.

f.       Close the “Group Policy Starter GPO Editor”.

g.      Click setting tab in the right pane of “Group Policy Management” and refresh the setting. You setting will show up in the right pane.

3.      Create a new Group Policy Object.

a.      Right click “Group Policy Objects” and click “New”.

b.      Give a name to the GPO and select the Starter GPO created in step 2.

c.      Click OK.

4.      Link the new Group Policy object to the domain.

a.      Right click your domain name and click “Link an existing GPO.”

b.      In the “select GPO” dialogue, select the GPO created in step 3.

c.      Click OK.

5.      On the client machine in the domain, run “gpupdate /force” or wait the group policy to be deployed to the client machine.

6.      On the client machine, enumerate the winRM listeners (winrm e winrm/config/listener). A new GPO source listener should be created automatically.

Configure WinRM HTTP listener without quick configure and Group Policy.

1.      Create an instance of HTTP Listener on all IPs:

winrm create winrm/config/Listener?Address=*+Transport=HTTP

2.      Create instance of HTTPS Listener on all IPs:

winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname="HOST";CertificateThumbprint="XXXXXXXXXX"}

Note: XXXXXXXXXX represents a 40-digit hex string; see help config.

For more on Configuration for WinRM.