5.2 WMI and some additional Windows services
5.2 WMI and some additional Windows services
5.2.1 Network Load-Balancing service
Available under Windows Server 2003 and Windows 2000 Server, the Network Load-Balancing provider consists of two WMI providers registered in the Root\MicrosoftNLB namespace: the NlbsNicProv provider, implemented as an instance and method provider, and the Microsoft|NLB_Provider|V1.0 provider, also implemented as an instance and method provider (see Table 5.1).
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Network Load Balancing Providers | ||||||||||||||||
| NlbsNicProv | Root/MicrosoftNLB | X | X | X | X | X | _X | |||||||||
| Microsoft|NLB_Provider|V1.0 | Root/MicrosoftNLB | X | X | X | X | X | X | X | X |
These two WMI providers support the classes listed in Table 5.2.
| Name | Type | Description |
|---|---|---|
| MicrosoftNLB_Cluster | Dynamic | Represents an instance of a Network Load-Balancing cluster. Only nodes that have remote control enabled contribute to the ClusterState property as reported in this class and respond to the methods invoked from this class. |
| MicrosoftNLB_ClusterSetting | Dynamic | Represents data that identifies the Network Load-Balancing cluster to which a node belongs. |
| MicrosoftNLB_ExtendedStatus | Dynamic | Used by the Network Load-Balancing provider to report error codes specific to Network Load Balancing. |
| MicrosoftNLB_Node | Dynamic | Represents an instance of a node within a Network Load-Balancing cluster. |
| MicrosoftNLB_NodeSetting | Dynamic | Represents the configuration data specific to a node. |
| MicrosoftNLB_PortRuleDisabled | Dynamic | Represents a port rule on a single node whose filtering mode is set to "Disable." Do not use this class unless you need to manage Windows 2000 clusters. Always use MicrosoftNLB_PortRuleEx for managing port rules if possible. |
| MicrosoftNLB_PortRuleEx | Dynamic | The MicrosoftNLB_PortRuleEx WMI class represents a port rule on a node. The provider will only return the instances for this class that correspond to the node upon which it resides. Consequently, to configure a node, the client must explicitly connect to that node |
| MicrosoftNLB_PortRuleFailover | Dynamic | Represents a Network Load-Balancing port rule set to single-host filtering mode. Do not use this class unless you need to manage Windows 2000 clusters. Always use MicrosoftNLB_PortRuleEx for managing port rules if possible. |
| MicrosoftNLB_PortRuleLoadbalanced | Dynamic | Represents a Network Load-Balancing port rule set to multiple-host filtering mode. Do not use this class unless you need to manage Windows 2000 clusters. Always use MicrosoftNLB_PortRuleEx for managing port rules if possible. |
| MicrosoftNLB_ClusterClusterSetting | Association | Associates an instance of the MicrosoftNLB_Cluster class to an instance of the MicrosoftNLB_ClusterSetting class. |
| MicrosoftNLB_NodeNodeSetting | Association | Associates an instance of the MicrosoftNLB_Node class to an instance of the MicrosoftNLB NodeSetting class. |
| MicrosoftNLB_NodeSettingPortRule | Association | Associates an instance of the MicrosoftNLB_NodeSetting class to instances of classes derived from MicrosoftNLB_PortRule. |
| MicrosoftNLB_ParticipatingNode | Association | Associates an instance of the MicrosoftNLB_Cluster class with participating MicrosoftNLB_Node class instances. |
| MicrosoftNLB_PortRule | Abstract Class | MicrosoftNLB_PortRule Is an abstract base class from which classes that represent port rules are derived. Do not use this class unless you need to manage Windows 2000 clusters. Use MicrosoftNLB_PortRuleEx. |
| NlbsNic | Dynamic | Allows the management of the NLB network adapter settings through a set of WMI static methods. |
The NlbsNicProv provider only supports the NlbsNic class, which exposes a series of static methods (Static Qualifier set to true) to manage the NLB adapter configuration. Basically, the methods can retrieve and set the configuration parameters available from the user interface in the network settings (see Figure 5.1).
Figure 5.1: The NLB network adapter user interface.
Note that the NlbsNic class does not expose any properties. All information must be retrieved and set through the methods listed in Table 5.3.
| Name | Description |
|---|---|
| ControlCluster | Changes local operational status of cluster or port. |
| GetCIusterConfiguration | Gets extended cluster configuration information. |
| GetCompatibleAdapterGuids | Gets the list of GUIDs of adapters compatible with NLBand the number of adapters currently bound to NLB. |
| QueryConfigurationUpdateStatus | Queries status of a pending asynchronous cluster configuration update. |
| RegisterManagementApplication | Registers a management application with NLB. |
| UnregisterManagementAppIication | Unregisters a management application with NLB. |
| UpdateClusterConfiguration | Asynchronously updates cluster configuration. |
Sample 5.1 shows how to proceed to retrieve information about the NLB network configuration settings.
Sample 5.1: Retrieving NLB network configuration settings
 |
1:<?xml version="1.0"?> .: 8:<package> 9: <job> ..: 13: <runtime> ..: 17: </runtime> 18: 19: <script language="VBScript" src="/books/2/679/1/html/2/..\Functions\TinyErrorHandler.vbs" /> 20: 21: <object prog reference="true''/> 22: 23: <script language="VBscript''> 24: <![CDATA[ ..: 28: Const cComputerName = "LocalHost" 29: Const cWMINameSpace = "root\MicrosoftNLB" ..: 62: ' ------------------------------------------------------------------------------- 63: ' Parse the command line parameters 64: strUserID = WScript.Arguments.Named("User'') 65: If Len(strUserID) = 0 Then strUserID ..: 80: Set objWMIClass = objWMIServices.Get ("NlbsNIC") 81: If Err.Number Then ErrorHandler (Err) 82: 83: intRC = objWMIClass.GetCompatibleAdapterGuids(arrayAdapterGuids, intNumBoundToNlb) 84: If intRC Then 85: WScript.Echo "Error getting Compatible Adapter GUID. (" & intRC & ")" 86: WScript.Quit (1) 87: End If 88: 89: For intIndice = 0 To intNumBoundToNlb - 1 90: WScript.Echo "Adapter GUID #" & intIndice + 1 & " : ................. " & _ 91: arrayAdapterGuids (intIndice) 92: 93: intRC = objWMIClass.GetClusterConfiguration (arrayAdapterGuids (intIndice), _ 94: strFriendlyName, _ 95: intGeneration, _ 96: arrayNetworkAddresses, _ 97: boolNLBBound, _ 98: strClusterNetworkAddress, _ 99: strClusterName, _ 100: strTrafficMode, _ 101: arrayPortRules, _ 102: intHostPriority, _ 103: strDedicatedNetworkAddress, _ 104: IntClusterModeOnStart, _ 105: boolPersistSuspendOnReboot, _ 106: boolRemoteControlEnabled, _ 107: intHashedRemoteControlPassword) 108: If intRC Then 109: WScript.Echo "Error getting Cluster Configuration. (" & intRC & ")" 110: WScript.Quit (1) 111: End If 112: 113: WScript.Echo "Adapter friendly name: ........... " & strFriendlyName 114: WScript.Echo "Generation: ...................... " & intGeneration 115: For Each varTemp In arrayNetworkAddresses 116: WScript.Echo "Network address(es): ............. " & varTemp 117: Next 118: WScript.Echo "NLB bound: ....................... " & boolNLBBound 119: WScript.Echo "Cluster network address: ......... " & strClusterNetworkAddress 120: WScript.Echo "Cluster name: .................... " & strClusterName 121: WScript.Echo "Traffic mode: .................... " & strTrafficMode 122: For Each varTemp In arrayPortRules 123: WScript.Echo "Rules: ........................... " & varTemp 124: Next 125: WScript.Echo "Host priority: ................... " & intHostPriority 126: WScript.Echo "Dedicated network address: ....... " & strDedicatedNetworkAddress 127: WScript.Echo "Cluster mode on startup: ......... " & intClusterModeOnStart 128: WScript.Echo "Persist suspend on reboot: ....... " & boolPersistSuspendOnReboot 129: WScript.Echo "Remote control enabled: .......... " & boolRemoteControlEnabled 130: WScript.Echo "Hashed remote control password: .. " & intHashedRemoteControlPassword 131: Next ...: 137: ]]> 138: </script> 139: </job> 140:</package> |
To retrieve NLB network settings, the first thing to do is to retrieve the adapter GUID (lines 83 through 87). This can be done with the GetCompatibleAdapterGuids static method exposed by the NlbsNIC class (line 83). Once the adapter GUID is known, it can be used to retrieve the cluster configuration with the GetClusterConfiguration static method. This method returns the information in a set of variables passed in the method parameters (lines 93 through 107). Once the GetClusterConfiguration static method is successfully invoked, the script displays the content of the variables with respect to their types (lines 113 through 130). The execution of Sample 5.1 shows the following output:
1: C:\>ViewNLBSSettings.wsf 2: Microsoft (R) Windows Script Host Version 5.6 3: Copyright (C) Microsoft Corporation 1996–2001. All rights reserved. 4: 5: Adapter GUID #1: ................. {8C4CECDF-1D96-4E2E-9B0C-066BFA705E0A) 6: Adapter friendly name: ........... Local Area Connection 7: Generation: ...................... 1 8: Network address(es): ............. 10.10.10.3/255.0.0.0 9: NLB bound: ....................... True 10: Cluster network address: ......... 172.10.10.1/255.255.0.0 11: Cluster name: .................... nlb.lissware.net 12: Traffic mode: .................... UNICAST 13: Rules: ........................... ip=255.255.255.255 protocol=BOTH start=0 end=65535 mode=MULTIPLE affinity=SINGLE 14: Host priority: ................... 1 15: Dedicated network address: ....... 10.10.10.3/255.0.0.0 16: Cluster mode on startup: ......... 1 17: Persist suspend on reboot: ....... False 18: Remote control enabled: .......... False 19: Hashed remote control password: .. 0 We recognize some of the information shown in Figure 5.1, such as the cluster IP address (line 10) or the cluster traffic mode (line 12).
The NlbsNIC class exposes many other methods (see Table 5.3). For instance, the ControlCluster method can be used to control the cluster state, while the UpdateClusterConfiguration method can be used to update the cluster configuration settings. Because this method asynchronously updates the configuration settings (note: do not confuse with the asynchronous scripting techniques), it is possible to get the update status by invoking the QueryConfiguration UpdateStatus method. This summarizes the capabilities of the NblsNIC class supported by the NlbsNICProv provider. As usual, WMI CIM Studio or the LoadCIMinXL.Wsf script (see Sample 4.32 in the appendix) can be used to retrieve information about these classes with their methods.
The Microsoft|NLB_Provider|V1.0 provider supports all the other classes listed in Table 5.2. These classes represent the node and cluster configuration settings as well but in an object model typical to the CIM repository class representation (instances, associations, etc.). For instance, since a cluster is always made of nodes, and since nodes and clusters have some specific configuration settings, the object model implemented in the CIM repository is made up of associations.
If we start looking from the MicrosoftNLB_Node class, we can see that this class is associated with (see Figure 5.2):
-
The MicrosoftNLB_NodeSetting class via MicrosoftNLB_NodeNodeSetting association class
-
The MicrosoftNLB_Cluster class with MicrosoftNLB_ParticipatingNode association class
Figure 5.2: The NLB class associations.
As part of the node settings, we also have the port rules defining the IP filtering rules. Therefore, the MicrosoftNLB_NodeSetting class is associated with the MicrosoftNLB_PortRule class, which has three subclasses: MicrosoftNLB_PortRuleDisabled, MicrosoftNLB_PortRuleFailover, and MicrosoftNLB_PortRuleLoadbalanced. In the same way, the MicrosoftNLB_ Cluster is associated with the MicrosoftNLB_ClusterSetting class. This object model is shown with WMI CIM Studio (see Figure 5.3).
Figure 5.3: The Node and Cluster classes.
It is important to note that since no event provider is implemented, this means that any WMI event subscriptions require the WITHIN statement in the WQL event query.
5.2.2 Cluster service
Registered in the Root\MSCluster namespace, the WMI Cluster support is implemented with three WMI providers, as shown in Table 5.4. These providers are available under Windows Server 2003 only.
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Cluster Providers | ||||||||||||||||
| Cluster Event Provider | Root/MSCluster | X | X | |||||||||||||
| MS_CLUSTER_CLASS_PROVIDER | Root/MSCluster | X | X | X | X | |||||||||||
| MS_CLUSTER_PROVIDER | Root/MSCluster | X | X | X | X | X | X | X |
In total more than 30 classes are supported by these providers. The supported classes are listed in Table 5.5.
| Name | Type | Description |
|---|---|---|
| MSCIuster_Cluster | Dynamic | Represents a duster. |
| MSCIuster_Network | Dynamic | Represents cluster networks, which define a network as a connection between network interfaces on the same subnet. |
| MSCluster_Networklnterface | Dynamic | Represents the network interface used by the cluster. |
| MSCIuster_Node | Dynamic | Represents a duster node. |
| MSCIuster_Resource | Dynamic | Represents a duster resource. |
| MSCluster_ResourceGroup | Dynamic | Represents a duster group. |
| MSCIuster_ResourceType | Dynamic | Represents a resource type. |
| MSCIuster_Service | Dynamic | Represents a Cluster service is a Windows NT/Windows 2000 component used to control server cluster activities on a single node. |
| MSCluster_CIusterToNetwork | Association | Represents the networks the duster uses for communication. |
| MSCluster_CIusterToNetworklnterface | Association | Represents the network interfaces the duster has installed on the nodes it manages. |
| MSCIuster_ClusterToNode | Association | Association class that provides access to the nodes in a cluster. |
| MSCIuster_ClusterToQuorumResource | Association | Represents the cluster quorum resource. |
| MSCIuster_ClusterToResource | Association | Represents the resources in a cluster. |
| MSCIuster_ClusterToResourceGroup | Association | Provides access to the groups in a cluster. |
| MSCIuster_ClusterToResourceType | Association | Represents the groups in the cluster. |
| MSCluster_NetworkToNetworkInterface | Association | Represents the network interfaces connected to a network. |
| MSCIuster_NodeToActiveGroup | Association | Represents the groups active on a node. |
| MSCIuster_NodeToActiveResource | Association | Represents the resources active on a node. |
| MSCluster_NodeToHostedService | Association | Represents a service managed by the duster as a resource. |
| MSCluster_NodeToNetworklnterface | Association | Represents the network interfaces connected to a node. |
| MSCIuster_ResourceGroupToPreferredNode | Association | Represents a list of the resource groups and their preferred nodes list. |
| MSCIuster_ResourceGroupToResource | Association | Represents the resources in a group. |
| MSCIuster_ResourceToDependentResource | Association | Represents the dependencies of a resource. |
| MSCluster_ResourceToPossibleOwner | Association | Represents a list of the resources and their possible owner nodes. |
| MSCIuster_ResourceTypeToResource | Association | Represents resources of a particular type. |
| MSCIuster_Event | Extrinsic Event | Represents a cluster event. |
| MSCIuster_EventGroupStateChange | Extrinsic Event | Represents a group state change event. |
| MSCluster_EventObjectAdd | Extrinsic Event | Represents an add object event. An add object event is generated when a cluster object is added to the cluster. |
| MSCluster_EventObjectRemove | Extrinsic Event | Represents a remove object event. A remove object event is generated when a cluster object is removed from the cluster. |
| MSCIuster_EventPropertyChange | Extrinsic Event | Represents a property change event. A property change event is generated when a cluster object property is changed. |
| MSCIuster_EventResourceStateChange | Extrinsic Event | Represents a resource state change event. |
| MSCIuster_EventStateChange | Extrinsic Event | Represents a state change event. A state change event is generated when the state of a cluster changes. |
An interesting point concerns the presence of the Cluster WMI event provider. As shown in Table 5.5, this provider supports seven extrinsic event classes, which can be used to track any cluster state modifications. All extrinsic event classes are derived from the MSCluster_Event superclass. Therefore, a WQL query such as
Select * From MSCluster_Event
will detect all changes supported by the event provider and related to the cluster.
Among the 30 classes in Table 5.5, the most interesting ones from a management perspective are the MSCluster_Node, MSCluster_Cluster, MSCluster_Service, MSCluster_ResourceGroup, and MSCluster_Resource. For instance, with the MSCluster_Node class, it is possible to enable the cluster node event log replication at the node level by configuring the EnableEventLogReplication property. With the MSCluster_Cluster SetQuorumResource method, it is possible to define the quorum resources and customize the Admin extension resources. The MSCluster_Service AddNode and EvictNode methods allow the addition and the removal of cluster nodes. This class also allows the start and stop of the cluster service, since it is a class derived from the CIM_Service superclass. And, last but not least, with the MSCluster_ResourceGroup and MSCluster_Resource classes, it is possible to bring a cluster resource on-line or off-line. It is also possible to move a resource to another cluster node. As usual, by using WMI CIM Studio or the LoadCIMinXL.Wsf script, you can gather more information about the class properties and the methods they expose.
Because a cluster consists of various components, the WMI classes are linked together with a collection of association classes. For instance, Figure 5.4 illustrates the associations in place for the MSCluster_Cluster class.
Figure 5.4: The MSCluster_Cluster class associations.
5.2.3 Terminal Server service
To support the WMI management of Terminal Services under Windows Server 2003, several providers are registered in the Root\CIMv2 namespace. Basically, there is one WMI provider per management function supported from WMI. This huge number of providers makes the situation a little bit confusing compared with the two previous Windows services. Therefore, we will examine this service in more detail.
Each provider supports one class from Table 5.6. You can determine the provider that supports a selected class by simply looking at the provider name, since the provider name contains the class name. For instance, the Win32_WIN32_TERMINALSERVICETOSETTING_Prov provider supports the Win32_TerminalServiceToSetting class. Of course, this is a peculiarity of the Terminal Services providers naming convention. Previously, to determine which supported a selected class, you would check the Provider Qualifier of the class. Even if there is one provider per class, this doesn't change anything from a scripting point of view. This WMI model is mainly designed to customize the Terminal Services configuration settings. The only interesting point to note is that none of the providers is implemented as an event provider, which implies the use of the WITHIN statement when monitoring Terminal Services settings. The supported classes are shown in Table 5.7.
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Terminal Server Providers | ||||||||||||||||
| Win32_WIN32_TERMINAL_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TERMINALSERVICE_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TERMINALSERVICESETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TERMINALSERVICETOSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TERMINALTERMINALSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | ||||||||
| Win32_WIN32_TSACCOUNT_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSCLIENTSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSENVIRONMENTSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSGENERALSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSLOGONSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSNETWORKADAPTERLISTSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSNETWORKADAPTERSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSPERMISSIONSSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSREMOTECONTROLSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSSESSIONDIRECTORY_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSSESSIONDIRECTORYSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X | |||||||
| Win32_WIN32_TSSESSIONSETTING_Prov | Root/CIMV2 | X | X | X | X | X | X | X | X |
| Name | Type | Description |
|---|---|---|
| Win32_Terminal | Dynamic | The Win32_Terminal class is the element of the Terminal Setting association where groups such as: General, Logon, Session, Environment, Remote Control, Client, Network Adapter, and Permission are several configuration setting dasses. |
| Win32_TerminalService | Dynamic | The Win32_TerminalService class provides Terminal Service load-balancing indicators. |
| Win32_TerminalServiceSetting | Dynamic | The Win32_TerminalServiceSetting class defines the configuration for TerminalServerSetting. This includes capabilities such as Terminal Server Mode, Licensing, Active Desktop, Permissions Capability, Deletion of Temporary folders, and Temporary folders per session. |
| Win32_TSAccount | Dynamic | The Win32_TSAccount class allows deleting an existing account on the Win32_Terminal class and Modify exisiting Permissions. |
| Win32_TSClientsetting | Dynamic | The Win32_TSCIientSetting class defines the configuration for Win32_Terminal. This includes capabilities such as Connection policy, printer, drive, clipboard mappings, color depth, and connection settings. |
| Win32_TSEnvironmentSetting | Dynamic | The Win32_TSEnvironmentSetting class defines the configuration for Win32_Terminal. This indudes capabilities such as Initial program policy. |
| Win32_TSGeneralSetting | Dynamic | The Win32_TSGeneralSetting includes capabilities such as Protocol, Transport, Comment, Windows authentication, and Encryption Level. |
| Win32_TSLogonSetting | Dynamic | The Win32_TSLogonSetting class allows configuring logon settings such as Username, Domain, and Password. |
| Win32_TSNetworkAdapterListSetting | Dynamic | The Win32_TSNetworkAdapterListSetting class enumerates IP address, GUID, and Name of the Network Adapter. |
| Win32_TSNetworkAdapterSetting | Dynamic | The Win32_TSNetworkAdapterSetting class defines the configuration for Win32_Terminal. This includes capabilities such as Network Adapter, Maximum Connections, etc. |
| Win32_TSPermissionsSetting | Dynamic | The Win32_TSPermissionsSetting class allows granting permissions to new accounts and restoring default permissions on the terminal. |
| Win32_TSRemoteControlSetting | Dynamic | The Win32_TSRemoteControlSetting class defines the configuration for Win32_Terminal. This includes capabilities such as Remote Control policy. |
| Win32_TSSessionDirectory | Dynamic | The Win32_TSSessionDirectory class defines the configuration for Win32_TSSessionDirectorySetting. This includes capabilities such as Session Directory store, Cluster Name, and Server IP address. |
| Win32_TSSessionSetting | Dynamic | The Win32_TSSessionSetting class defines the configuration for Win32_Terminal. This includes capabilities such as Time-limits, Disconnection, and Reconnection actions. |
| Win32_TerminalServiceToSetting | Association | The Win32_TerminalServiceToSetting class is an association with Win32_Terminal Service as the Element and Win32_TerminalServiceSetting as the Setting property that includes Terminal Server Mode, Licensing, Active Desktop, Permissions Capability, Deletion of Temporary folders, and Temporary folders per session. |
| Win32_TerminalTerminalSetting | Association | The Win32_TerminalTerminalSetting class represents an association between a Terminal and its configuration settings. |
| Win32_TSSessionDirectorySetting | Association | The Win32_TSSessionDirectorySetting class is an association with Win32_Terminal Service as the Element and Win32_TSSessionDirectory as the Setting property that includes Terminal Server Session Directory Location, Cluster Name, and SessionDirectoryActive properties. |
With these classes, you can manage the settings available from the "Terminal Services Configuration" MMC. With the Win32_TerminalServiceSetting class, you can manage the settings shown in the "Server Settings" folder (see Figure 5.5, Server Settings view—top). With all other classes you can manage the settings of the connection transport visible in the "Connections" folder (see Figure 5.5, Connections view—bottom).
Figure 5.5: The Terminal Services Configuration MMC.
5.2.3.1 The Terminal Server configuration
To configure the Terminal Server settings, the Win32_TerminalServiceSetting class exposes several methods. Each method corresponds to a setting of the "Server Settings."
As shown in the Sample 5.2 code snippet, the license mode can be changed with the ChangeMode method (line 267) and the corresponding value shown in Table 5.8.
| License Mode | Value | Win32_TerminalServiceSetting Method/Property |
|---|---|---|
| Admin | 1 | ChangeMode() method |
| PerDevice | 2 | |
| PerSession | 3 | |
| Personal | 4 | |
| Security Mode | ||
| Full | 0 | UserPermission property |
| Relaxed | 1 | |
| TS Connections | ||
| Allow | 1 | SetAllowTSConnections() method |
| Deny | 0 | |
| Home Directory | ||
| C:\MyHomePath | SetHomeDirectory() method | |
| Profile Path | ||
| C:\MyProfilePath | SetProfilePath() method | |
| Delete Temp Folders | ||
| Enabled | 1 | SetPolicyPropertyName() method |
| Disabled | 0 | |
| Use Temp Folders | ||
| Enabled | 1 | SetPolicyPropertyName() method |
| Disabled | 0 | |
| Single Session | ||
| Enabled | 1 | SetSingleSession() method |
| Disabled | 0 | |
| Time Zone Redirection | ||
| Enabled | 1 | SetTimeZoneRedirection() method |
| Disabled | 0 |
Sample 5.2: Changing the license mode
|
...: ...: ...: 264: 265: ' License Mode --------------------------------------------------------------------- 266: If boolChangeLicenseMode Then 267: intRC = objWMIInstance.ChangeMode (intChangeLicenseMode) ...: 270: If intRC = 0 Then 271: WScript.Echo "TS license mode settings configured." 272: Else 273: WScript.Echo ''Failed to configure license mode settings (" & intRC & ")." 274: End If 275: End If 276: ...: ...: ...: |
The same logic applies to change the other server settings shown in Figure 5.5, Server Settings view. However, a specific method must be used for each. Therefore the Win32_TerminalServiceSetting class exposes the SetAllowTSConnections, SetHomeDirectory, SetProfilePath, SetSingleSession, and SetTimeZoneRedirection methods. The corresponding values listed in Table 5.8 must be used as the method parameter. In some cases, to customize the Win32_TerminalServiceSetting instance, it is necessary to update a property. This is the case for the security mode. In such a case, the script must set the UserPermission property (see Sample 5.3, lines 279 through 281) with the corresponding value (see Table 5.8).
Sample 5.3: Changing the security mode
|
...: ...: ...: 276: 277: ' Security Mode ------------------------------------------------------------------- 278: If boolSecurityMode Then 279: objWMIInstance.UserPermission = intSecurityMode 280: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 281: wbemFlagReturnWhenComplete) ...: 284: WScript.Echo "TS security mode configured." 285: End If 286: ...: ...: ...:
|
A final peculiarity concerning the Win32_TerminalServiceSetting class is the modification of the temporary folder settings (see Sample 5.4). These settings must be set with the SetPolicyPropertyName method (lines 325 and 326, lines 338 and 339), which accepts two parameters: The first parameter corresponds to the property name to configure, and the second parameter corresponds to the value assigned to the selected property name.
Sample 5.4: Changing the temporary folder settings
|
...: ...: ...: 322: 323: ' Delete Temp Folders --------------------------------------------------------------- 324: If boolDeleteTempFolders Then 325: intRC = objWMIInstance.SetPolicyPropertyName ("DeleteTempFolders", _ 326: intDeleteTempFolders) ...: 329: If intRC = 0 Then 330: WScript.Echo "TS Delete Temp Folders setting configured." 331: Else 332: WScript.Echo "Failed to configure Delete Temp Folders setting('' & intRC & ")." 333: End If 334: End If 335: 336: ' Use Temp Folders ------------------------------------------------------------------ 337: If boolUseTempFolders Then 338: intRC = objWMIInstance.SetPolicyPropertyName ("UseTempFolders", _ 339: intUseTempFolders) ...: 342: If intRC = 0 Then 343: WScript.Echo "TS Use Temp Folders setting configured." 344: Else 345: WScript.Echo "Failed to configure Use Temp Folders setting('' & intRC & ")." 346: End If 347: End If 348: ...: ...: ...: |
5.2.3.2 The Terminal Server connections configuration
To manage the Terminal Services connections settings, all other classes from Table 5.7 must be used. Even if the overall logic is the same as for the "Server Settings" with the Win32_TerminalServiceSetting class, the Terminal Services connections settings are a bit more complex to set up due to the number of configuration possibilities. In any case, the first action is to retrieve the connection settings instance. By default the "RDP-tcp" connection is the only connection setting instance available (see Figure 5.5, Connections view).
5.2.3.2.1 Enabling/disabling the Terminal Server connections
Enabling or disabling the connection settings is the easiest configuration to perform, since it involves the invocation of the Enable method of the Win32_Terminal class (see Sample 5.5). A parameter value of 1 enables the connection settings instance, while a parameter value of 0 disables it (line 594). This action corresponds to a right click on the connection name available in the MMC and selecting "Enable connection" or "Disable connection" (in the "All tasks" submenu).
Sample 5.5: Enabling/disabling the Terminal Services connections
|
...: ...: ...: 587: 588: ' Enable/Disable ---------------------------------------------------------------------------- 589: If boolTerminalEnable Then 590: Set objWMIInstance = objWMIServices.Get ("Win32_Terminal='" & _ 591: strTerminalName & "'") 592: If Err.Number Then ErrorHandler (Err) 593: 594: intRC = objWMIInstance.Enable (intTerminalEnable) ...: 597: If intRC = 0 Then 598: If intTerminalEnable = 1 Then 599: WScript.Echo "TS enabled." 600: Else 601: WScript.Echo "TS disabled." 602: End If 603: Else 604: WScript.Echo "Failed to enable/disable Terminal Server (" & intRC & ")." 605: End If 606: End If 607: ...: ...: ...: |
5.2.3.2.2 The Terminal Services remote control settings
To configure the remote control connection settings, the RemoteControl method exposed by the Win32_TSRemoteControlSetting class must be invoked. To properly customize all combinations available from the user interface (see Figure 5.6), it is necessary to set up the RemoteControlPolicy property before any other settings.
Figure 5.6: The Terminal Services remote control configuration.
To set up the various combinations, the two parameters (the RemoteControl method parameter and the RemoteControlPolicy property) must combine different values. Table 5.9 shows the various combinations for both values with their corresponding settings.
| LevelOfControl | RemoteControlPolicy | |
|---|---|---|
| Use remote control with default user settings | 0 | 1 |
| Do not allow remote control | 0 | 0 |
| Use remote control with the following settings | ||
| ||
| 3 | 0 |
| 1 | 0 |
| ||
| 4 | 0 |
| 2 | 0 |
Sample 5.6 shows the coding logic to update the RemoteControlPolicy property (lines 614 through 616) and invoke the RemoteControl method (lines 619 and 620) if the policy is enabled.
Sample 5.6: Configuring the Terminal Services remote control settings
|
...: ...: ...: 607: 608: ' Remote Control ------------------------------------------------------------------------- 609: If boolRemoteControl Then 610: Set objWMIInstance = objWMIServices.Get ("Win32_TSRemoteControlSetting=' " & _ 611: strTerminalName & "'") ...: 614: objWMIInstance.RemoteControlPolicy = intRemoteControlPolicy 615: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 616: wbemFlagReturnWhenComplete) ...: 619: If intRemoteControlPolicy = 0 Then 620: intRC = objWMIInstance.RemoteControl (intLevelOfControl) ...: 622: End If 623: 624: If intRC = 0 Then 625: WScript.Echo "TS Remote Control policy configured." 626: Else 627: WScript.Echo "Failed to configure the Remote Control policy (" & intRC & ")." 628: End If 629: End If 630: ...: ...: ...: |
5.2.3.2.3 The Terminal Services network adapter and connection limit settings
To set up the connection limit, it is necessary to update the MaximumConnections property exposed by the Win32_TSNetworkAdapterSetting instance representing the Terminal Services network adapter and connection limit settings (see Figure 5.7).
Figure 5.7: The Terminal Service connection limit settings.
A value of 4,294,967,295 (which is 2^32 - 1, the biggest unsigned integer on 32 bits) sets the connection limit to unlimited. Any other value determines the connection limit in seconds. Sample 5.7 illustrates the coding logic (lines 637 through 639).
Sample 5.7: Configuring the Terminal Services maximum connection settings
|
...: ...: ...: 630: 631: ' Maximum TS connections ------------------------------------------------------------------ 632: If boolMaximumConnections Then 633: Set objWMIInstance = objWMIServices.Get ("Win32_TSNetworkAdapterSetting='" & _ 634: strTerminalName & "'") ...: 637: objWMIInstance.MaximumConnections = longMaximumConnections 638: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 639: wbemFlagReturnWhenComplete) ...: 642: If longMaximumConnections = cNoConnectionLimit Then 643: WScript.Echo "TS has no connections limit configured." 644: Else 645: WScript.Echo "TS has " & longMaximumConnections & " connections limit configured." 646: End If 647: End If 648: 649: ' Adapter --------------------------------------------------------------------------------- 650: If boolAdapter Then 651: Set objWMIInstance = objWMIServices.Get ("Win32_TSNetworkAdapterSetting='" & _ 652: strTerminalName & "'") ...: 655: If UCase (strIPAddress) = "ALL" Then 656: intRC = objWMIInstance.SelectAllNetworkAdapters ...: 658: Else 659: intRC = objWMIInstance.SelectNetworkAdapterIP (strIPAddress) ...: 661: End If 662: 663: If intRC = 0 Then 664: WScript.Echo "TS adapter configured." 665: End If 666: End If 667: ...: ...: ...: |
From the Win32_TSNetworkAdapterSetting instance it is also possible to determine which adapter is compatible with the selected Terminal Services Transport. To set up all adapters, the SelectAllNetworkAdapters method must be invoked (line 656). To select a specific network adapter, the SelectNetworkAdapterIP method must be invoked with the adapter IP address as a parameter (line 659).
5.2.3.2.4 The Terminal Services encryption and authentication settings
To configure the encryption level, the SetEncryptionLevel method exposed by the Win32_TSGeneralSetting class must be invoked. To configure the authentication method, the WindowsAuthentication property exposed by the Win32_TSGeneralSetting instance must be updated.
Figure 5.8 shows the various settings available, while Table 5.10 contains the miscellaneous values.
| MinEncryptionLevel | WindowsAuthentication | |
|---|---|---|
| High | 3 | |
| Client Compatible | 2 | |
| Use standard Windows Authentication checked | 1 | |
| Use standard Windows Authentication unchecked | 0 |
Figure 5.8: The Terminal Services general connection settings.
Sample 5.8 illustrates the coding logic.
Sample 5.8: Configuring the Terminal Services encryption and authentication levels
|
...: ...: ...: 667: 668: ' Encryption level ------------------------------------------------------------------------ 669: If boolEncryptionLevel Then 670: Set objWMIInstance = objWMIServices.Get ("Win32_TSGeneralSetting='" & _ 671: strTerminalName & "'") ...: 674: intRC = objWMIInstance.SetEncryptionLevel(intEncryptionLevel) ...: 677: WScript.Echo "TS encryption level configured." 678: End If 679: 680: ' Windows Authentication ------------------------------------------------------------------ 681: If boolWinAuthentication Then 682: Set objWMIInstance = objWMIServices.Get ("Win32_TSGeneralSetting= '" & _ 683: strTerminalName & "'") ...: 686: objWMIInstance.WindowsAuthentication = intWinAuthentication 687: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 688: wbemFlagReturnWhenComplete) ...: 691: If intRC = 0 Then 692: WScript.Echo "TS Windows authentication configured." 693: End If 694: End If 695: ...: ...: ...: |
5.2.3.2.5 The Terminal Services client settings
To set up the Terminal Services default client settings, various methods and properties exposed by the Win32_TSClientSetting class must be used. Figure 5.9 shows the settings available.
Figure 5.9: The Terminal Services default client settings.
The number of values that could be set to customize the Terminal Services default client settings is quite confusing, because it is sometimes necessary to update a property directly by assigning a new value; at other times, it may be necessary to invoke a method instead (see Table 5.11).
| ConnectionPolicy | |
| Use connection settings from user settings unchecked | 0 |
| Use connection settings from user settings checked | 1 |
| ConnectClientDrivesAtLogon | |
| 0 |
| 1 |
| ConnectPrinterAtLogon | |
| 0 |
| 1 |
| DefaultToClientPrinter | |
| 0 |
| 1 |
| ColorDepthPolicy | |
| Limit color depth unchecked | 1 |
| Limit color depth checked | 0 |
| ColorDepth | |
| 1 |
| 2 |
| 3 |
| 4 |
| DriveMapping | |
| Drive mapping unchecked | 0 |
| Drive mapping checked | 1 |
| WindowsPrinterMapping | |
| Windows printer mapping unchecked | 0 |
| Windows printer mapping checked | 1 |
| LPTPortMapping | |
| LPT port mapping unchecked | 0 |
| LPT port mapping checked | 1 |
| COMPortMapping | |
| COM port mapping unchecked | 0 |
| COM port mapping checked | 1 |
| Clipboard Mapping | |
| Clipboard mapping unchecked | 0 |
| Clipboard mapping checked | 1 |
| AudioMapping | |
| Audio mapping unchecked | 0 |
| Audio mapping checked | 1 |
By updating the ConnectionPolicy property exposed by the Win32_ TSClientSetting class, a script will perform the exact same change as selecting the "Use connection settings from user settings" check box. Sample 5.9 shows the coding logic.
Sample 5.9: Configuring the Terminal Services client connection policy settings
|
...: ...: ...: 695: 696: ' User Connection settings ---------------------------------------------------------------- 697: If boolConnUserSettings Then 698: Set objWMIInstance = objWMIServices.Get ("Win32_TSClientSetting='" & _ 699: strTerminalName & "'") ...: 702: objWMIInstance.ConnectionPolicy = intConnUserSettings 703: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 704: wbemFlagReturnWhenComplete) ...: 707: If intConnUserSettings = 0 Then 708: intRC = objWMIInstance.ConnectionSettings (intConnClientDrivesAtLogon, _ 709: intConnClientPrintersAtLogon, _ 710: intDefaultToMainClientPrinter) ...: 712: End If 713: 714: If intRC = 0 Then 715: WScript.Echo "TS user connection settings configured." 716: Else 717: WScript.Echo "Failed to configure user connection settings (" & intRC & ")." 718: End If 719: End If 720: ...: ...: ...: |
If the "Use connection settings from user settings" check box is unchecked, a client connection policy must be defined. Therefore, the three check boxes in the "Connection" frame (See Figure 5.9) can be configured. This is the reason why Sample 5.9 invokes the ConnectionSettings method exposed by the Win32_TSClientSetting class and sets the state of the three check boxes (lines 708 through 710).
Regarding the color depth policy, the overall logic is the same as for the client connection policy. Sample 5.10 shows the logic. To define the color depth policy, the SetColorDepthPolicy method must be invoked with a parameter value defining the check box state (line 727). Table 5.11 lists the miscellaneous values to use. If the color depth policy is enabled, the color depth must be set by invoking the SetColorDepth method, with a parameter value corresponding to the number of bits defining the color depth (line 731).
Sample 5.10: Configuring the Terminal Services client color depth policy settings
|
...: ...: ...: 720: 721: ' Color depth settings -------------------------------------------------------------------- 722: If boolColorDepth Then 723: Set objWMIInstance = objWMIServices.Get ("Win32_TSClientSetting='" & _ 724: strTerminalName & "'") ...: 727: intRC = objWMIInstance.SetColorDepthPolicy (intColorDepth) ...: 730: If intColorDepth = 0 Then 731: intRC = objWMIInstance.SetColorDepth (intColorDepthBit) ...: 733: End If 734: 735: If intRC = 0 Then 736: WScript.Echo "TS color depth settings configured." 737: Else 738: WScript.Echo "Failed to configure color depth settings (" & intRC & ")." 739: End If 740: End If 741: ...: ...: ...: |
The final settings concerning the client connection settings concern the resource mappings. These settings correspond to the drive, Windows printer, LPT port, COM port, clipboard, and audio mapping (see Figure 5.9). Here, the logic is a little bit different, since there is no dedicated property or method to use for each setting. To configure these parameters, the SetClientProperty method exposed by the Win32_TSClientSetting class must be used. Sample 5.11 shows the logic to use for the LPT port mapping, but the technique is the same for all mappings. Basically, the first method parameter contains the property name and the second parameter a Boolean value defining the state (line 748). You can check the Win32_TSClientSetting class properties to determine the mapping properties to use during the method invocation.
Sample 5.11: Configuring the Terminal Services client mapping settings
|
...: ...: ...: 741: 742: ' LPT Resource mapping -------------------------------------------------------------------- 743: If Len (boolLPTMapping) Then 744: Set objWMIInstance = objWMIServices.Get ("Win32_TSClientSetting='" & _ 745: strTerminalName & "'") ...: 748: intRC = objWMIInstance.SetClientProperty ("LPTPortMapping", boolLPTMapping) ...: 751: If intRC = 0 Then 752: WScript.Echo "TS LPT port mapping configured." 753: Else 754: WScript.Echo "Failed to configure LPT port mapping (" & intRC & ")." 755: End If 756: End If 757: ...: ...: ...: |
5.2.3.2.6 The Terminal Services environment settings
To configure the environment settings of the Terminal Services connection, the Win32_TSEnvironmentSetting class must be used. The first setting concerns the initial program policy (see Figure 5.10), which allows the startup of a specific application at logon time.
Figure 5.10: The Terminal Services connection environment settings.
As shown in Sample 5.12, to define the initial program policy the InitialProgramPolicy property must be updated (lines 844 and 845) accordingly to the values listed in Table 5.12. If the policy is enabled, the InitialProgram method exposed by the Win32_TSEnvironmentSetting class must be invoked (lines 849 through 852), with two parameters containing the program name and the initial program path, respectively.
| TS environment settings | InitialProgramPolicy |
|---|---|
| Override settings from user profile and Remote Desktop Connection or Terminal Services Client unchecked | 1 |
| Override settings from user profile and Remote Desktop Connection or Terminal Services Client checked | 0 |
Sample 5.12: Configuring the Terminal Services connection environment settings
|
...: ...: ...: 837: 838: ' Initial program ------------------------------------------------------------------------- 839: If boolInitialProgram Then 840: Set objWMIInstance = objWMIServices.Get ("Win32_TSEnvironmentSetting='" & _ 841: strTerminalName & "'") ...: 844: objWMIInstance.InitialProgramPolicy = intInitialProgramPolicy 845: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 846 wbemFlagReturnWhenComplete) ...: 849: If intInitialProgramPolicy = 0 Then 850: intRC = objWMIInstance.InitialProgram (strInitialProgramName, strInitialProgramPath) ...: 852: End If 853: 854: If intRC = 0 Then 855: WScript.Echo "TS initial program configured." 856: Else 857: WScript.Echo "Failed to configure initial program (" & intRC & ").' 858: End If 859: End If 860: 861: ' Display Wallpaper ----------------------------------------------------------------------- 862: If boolDisplayWallPaper Then 863: Set objWMIInstance = objWMIServices.Get ("Win32_TSEnvironmentSetting='" & _ 864: strTerminalName & "'") ...: 867: intRC = objWMIInstance.SetClientWallPaper (intDisplayWallPaper) ...: 870: If intRC = 0 Then 871: WScript.Echo "TS display wallpaper configured." 872: Else 873: WScript.Echo ''Failed to configure display wallpaper (" & intRC & ")." 874: End If 875: End If 876: ...: ...: ...: |
The wallpaper setting is set with the SetClientWallPaper method exposed by the Win32_TSEnvironmentSetting class. This method sets the ClientWallPaper property exposed by the same class. When the SetClientWallPaper method parameter is set to 1, the ClientWallPaper property is set to 1 as well and forces the display of the wallpaper on the client desktop.
5.2.3.2.7 The Terminal Services connection logon settings
The Win32_TSLogonSetting class configures the Terminal Services connection logon settings shown in Figure 5.11.
Figure 5.11: The Terminal Services connection logon settings.
As shown in Sample 5.13, to configure the client logon policy the ClientLogonInfoPolicy property exposed by the Win32_TSLogonSetting class must be updated (lines 883 through 885). If the policy is enabled, the logon parameters must be defined with the ExplicitLogon method exposed by the Win32_TSLogonSetting class (lines 888 through 893). The values to use are listed in Table 5.13.
Sample 5.13: Configuring the Terminal Services connection logon settings
|
...: ...: ...: 876: 877: ' Logon as -------------------------------------------------------------------------------- 878: If boolClientLogon Then 879: Set objWMIInstance = objWMIServices.Get ("Win32_TSLogonSetting='" & _ 880: strTerminalName & "'") ...: 883: objWMIInstance.ClientLogonInfoPolicy = intClientLogonPolicy 884: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 885 wbemFlagReturnWhenComplete) ...: 888: If intClientLogonPolicy= 0 Then 889: intRC = objWMIInstance.ExplicitLogon (strLogonUser, _ 890 strLogonDomain, _ 891 strLogonPassword) ...: 893: End If 894: 895: If intRC = 0 Then 896: WScript.Echo "TS client logon information configured." 897: Else 898: WScript.Echo "Failed to configure client logon information (" & intRC & ")." 899: End If 900: End If 901: 902: ' Prompt password ------------------------------------------------------------------------- 903: If boolPromptPassword Then 904: Set objWMIInstance = objWMIServices.Get ("Win32_TSLogonSetting='" & _ 905: strTerminalName & "'") ...: 908: intRC = objWMIInstance.SetPromptForPassword (intPromptPassword) ...: 911: If intRC = 0 Then 912: WScript.Echo "TS prompt password configured." 913: Else 914: WScript.Echo "Failed to configure prompt password (" & intRC & ") . ' 915: End If 916: End If 917: ...: ...: ...: |
| ClientLogonlnfoPolicy | |
| Use client-provided logon information | 1 |
| Always use the following logon information | 0 |
| PromptForPassword | |
| Always prompt for password unchecked | 0 |
| Always prompt for password checked | 1 |
To determine if the user must be prompted for the password, the SetPromptPassword method exposed by the Win32_TSLogonSetting class must be invoked (line 908). A value of 1 will prompt the user for the password.
5.2.3.2.8 The Terminal Services connection session settings
The Win32_TSSessionSetting class exposes properties to configure the Terminal Services connection session settings shown in Figure 5.12.
Figure 5.12: The Terminal Services connection session settings.
The overall logic shown in Sample 5.14 is the same as before. The Terminal Services session policy must be defined first (lines 924 through 926) by updating the TimeLimitPolicy property exposed by the Win32_TSSessionSetting class. The value to use is shown in Table 5.14. If the policy is enabled, the TimeLimit method exposed by the Win32_TSSessionSetting class will define the DisconnectedSessionLimit (line 930), ActiveSessionLimit (line 937), and IdleSessionLimit (line 944) properties. The values to use are listed in Table 5.14.
Sample 5.14: Configuring the Terminal Services connection session settings
|
...: ...: ...: 917: 918: ' User Session settings ------------------------------------------------------------------- 919: If boolUserTimeLimitSettings Then 920: Set objWMIInstance = objWMIServices.Get ("Win32_TSSessionSetting='" & _ 921: strTerminalName & "'") ...: 924: objWMIInstance.TimeLimitPolicy = intUserTimeLimitPolicy 925: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 926: wbemFlagReturnWhenComplete) ...: 929: If intUserTimeLimitPolicy = 0 Then 930: intRC = objWMIInstance.TimeLimit ("DisconnectedSessionLimit", intEndDiscSession) ...: 933: If intRC Then 934: WScript.Echo "Failed to configure disconnected session limit (" & intRC & ")." 935: End If 936: 937: intRC = objWMIInstance.TimeLimit ("ActiveSessionLimit", intActiveSessionLimit) ...: 940: If intRC Then 941: WScript.Echo "Failed to configure Active session limit (" & intRC & ")." 942: End If 943: 944: intRC = objWMIInstance.TimeLimit ("IdleSessionLimit", intIdleSessionLimit) ...: 947: If intRC Then 948: WScript.Echo "Failed to configure idle session limit (" & intRC & ")." 949: End If 950: End If 951: 952: WScript.Echo "TS user session settings configured." 953: End If 954: 955: ' Broken Session -------------------------------------------------------------------------- 956: If boolBrokenSession Then 957: Set objWMIInstance = objWMIServices.Get ("Win32_TSSessionSetting='" & _ 958: strTerminalName & "'") ...: 961: objWMIInstance.BrokenConnectionPolicy = intBrokenConnectionPolicy 962: objWMIInstance.Put_ (wbemChangeFlagCreateOrUpdate Or _ 963: wbemFlagReturnWhenComplete) ...: 966: If intBrokenConnectionPolicy = 0 Then 967: intRC = objWMIInstance.BrokenConnection (intBrokenConnectionAction) ...: 969: End If 970: 971: If intRC = 0 Then 972: WScript.Echo "TS broken connection action settings configured." 973: Else 974: WScript.Echo "Failed to configure broken connection action settings (" & intRC & ").' 975: End If 976: End If 977: ...: ...: ...: |
| TimeLimitPolicy | |
| Override user settings unchecked | 0 |
| Override user settings checked | 1 |
| DisconnectedSessionLimit | |
| |
| 0 |
| Delay in Min* 60* 1000 |
| ActiveSessionLimit | |
| |
| 0 |
| Delay in Min* 60* 1000 |
| IdleSessionLimit | |
| |
| 0 |
| Delay in Min* 60* 1000 |
| BrokenConnectionPolicy | |
| Override user settings unchecked | 1 |
| Override user settings checked | 0 |
| BrokenConnectionAction | |
| 0 |
| 1 |
| ReconnectionPolicy | |
| Override user settings checked | 1 |
The same logic applies for the broken session policy. The BrokenConnectionPolicy property exposed by the Win32_TSSessionSetting class must be set first (lines 961 through 963). If the policy is enabled, the BrokenConnectionAction property must be set with the BrokenConnection method (line 967).
5.2.3.2.9 The Terminal Services connection permissions settings
As we have seen in Chapter 4, managing the security often implies the manipulation of a security descriptor. However, to modify the Terminal Services connection permissions settings, it is necessary to invoke specific methods exposed by the Win32_TSPermissionsSetting class (see Figure 5.13).
Figure 5.13: The Terminal Services connection permission settings.
The Win32_TSPermissionsSetting class exposes the AddAccount method, which takes two parameters: the Domain\UserID account name and the permission value, which defines the right granted for the given account name (see Table 5.15, "Values" column).
| TS permissions settings | Values | Masks |
|---|---|---|
| Guest | 0 | 32 |
| User and Guest | 1 | 417 |
| Full control, User and Guest | 2 | 983999 |
To restore the default permissions, the Win32_TSPermissionsSetting class exposes the RestoreDefaults method. To delete an account granted on the Terminal Services connection settings, the Delete method exposed by the Win32_TSAccount class must be used. If the granted permissions must be modified, the Win32_TSAccount class exposes the ModifyPermissions and ModifyAuditPermissions methods. Both methods require an access mask (see Table 5.15, "Masks" column) and a Boolean value to determine if the access mask is granted or denied.
5.2.4 Windows Driver Model provider
The Windows Driver Model (WDM) provider is available from Windows 2000 and later. This provider gives access to WMI information exposed by drivers that are WDM enabled. WDM is an operating system interface through which hardware components (device drivers) provide information exposed by WMI (see Table 5.16). Actually, the WDM provider is made up of two providers registered in the Root\WMI namespace:
-
A class, instance, and method provider called WMIProv
-
An event provider called WMIEventProv
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| WDM Provider | ||||||||||||||||
| WMIProv | Root/WMI | X | X | X | X | X | X | X | X | X | X | |||||
| WMIProv | Root/MicrosoftNLB | X | X | X | X | X | X | X | ||||||||
| WMIEventProv | Root/WMI | X | X | X | X | |||||||||||
| WMIEventProv | Root/MicrosoftNLB | X | X |
We will not go into the details of the WDM operating system interface. However, to retrieve information from the WDM-enabled drivers, WDM drivers must expose WMI information loaded in the CIM repository. To determine the list of drivers exposing information in the CIM repository, it is possible to request instances of the WMIBinaryMofResource class (see Figure 5.14).
Figure 5.14: The WMIBinaryMofResource class instances.
The most interesting classes supported by the instance provider are summarized in Table 5.17.
| Name | Description |
|---|---|
| MSAcpi_ThermalZoneTemperature | ThermalZone temperature information |
| MSAcpiInfo | ACPI Table data |
| MSChangerParameters | Changer Parameters |
| MSChangerProblemDeviceError | Changer Errors |
| MSChangerProblemEvent | Changer Problem Warning |
| MSDeviceUI_FirmwareRevision | Firmware Revision |
| MSDiskDriver_Geometry | Disk Geometry |
| MSDiskDriver_Performance | Disk performance statistics |
| MSIde_PortDeviceInfo | Scsi Address |
| MSKeyboard_CIassInformation | Keyboard class driver information |
| MSKeyboard_ExtendedID | Keyboard port extended ID |
| MSKeyboard_PortInformation | Keyboard port driver information |
| MSMCAEvent_CPUError | MCA CPU Error Event |
| MSMCAEvent_InvalidError | MCA Unknown Error Event |
| MSMCAEvent_MemoryError | MCA Memory Error Event |
| MSMCAEvent_MemoryPageRemoved | Memory page has been removed |
| MSMCAEvent_PCIBusError | MCA PCI Bus Error Event |
| MSMCAEvent_PCIComponentError | MCA PCI Platform Component Error Event |
| MSMCAEvent_PlatformSpecificError | MCA Platform Specific Error Event |
| MSMCAEvent_SMBIOSError | MCA SMBIOS Error Event |
| MSMCAEvent_SwitchToCMCPolling | CMC handling switched from interrupt driver to polling |
| MSMCAEvent_SwitchToCPEPolling | CPE handling switched from interrupt driver to polling |
| MSMCAEvent_SystemEventError | MCA Platform IPMI System Eventlog Error Event |
| MSMCAInfo_RawCMCEvent | This contains a CMC event |
| MSMCAInfo_RawCorrectedPlatformEvent | This contains a Corrected Platform event |
| MSMCAInfo_RawMCAData | This contains the raw MCA logs |
| MSMCAInfo_RawMCAEvent | This contains a MCA event |
| MSMouse_ClassInformation | Mouse class driver information |
| MSMouse_PortInformation | Mouse port driver information |
| MSNdis_CurrentLookahead | NDIS Current Lookahead |
| MSNdis_CurrentPacketFilter | NDIS Current Packet Filter |
| MSNdis_DeviceWakeOnMagicPacketOnly | This control decides whether the network devioe should wake up the system only on receiving a Magic packet |
| MSNdis_DriverVersion | NDIS Driver Version |
| MSNdis_EnumerateAdapter | NDIS Enumerate Adapter |
| MSNdis_HardwareStatus | NDIS Hardware Status |
| MSNdis_LinkSpeed | NDIS Link Speed |
| MSNdis_MacOptions | NDIS MAC Options |
| MSNdis_MaximumFrameSize | NDIS Maximum Frame Size |
| MSNdis_MaximumLookahead | NDIS Maximum Lookahead Supported |
| MSNdis_MaximumSendPackets | NDIS Maximum Send Packets |
| MSNdis_MaximumTotalSize | NDIS Maximum Packet Total Size |
| MSNdis_MediaConnectStatus | NDIIS Media Connect Status |
| MSNdis_MediaInUse | NDIS Media Types In Use |
| MSNdis_MediaSupported | NDIS Media Types Supported |
| MSNdis_NdisEnumerateVc | NDIS Enumerate VC |
| MSNdis_NotifyAdapterArrival | NDIS Notify Adapter Arrival |
| MSNdis_NotifyAdapterRemoval | NDIS Notify Adapter Removal |
| MSNdis_NotifyVcArrival | NDIS Notify VC Arrival |
| MSNdis_NotifyVcRemoval | NDIS Notify VC Removal |
| MSNdis_PhysicalMediumType | NDIS Physical Medium Type |
| MSNdis_ReceiveBlockSize | NDIS Receive Block Size |
| MSNdis_ReceiveBufferSpace | NDIS Receive Buffer Space |
| MSNdis_ReceiveError | NDIS Receive Errors |
| MSNdis_ReceiveNoBuffer | NDIS Receive No Buffer |
| MSNdis_ReceivesOk | NDIS Receives OK |
| MSNdis_StatusDevicePowerOff | NDIS Device Power Off Notification |
| MSNdis_StatusDevicePowerOn | NDIS Device Power On Notification |
| MSNdis_StatusLinkSpeedChange | NDIS Status Link Speed Change |
| MSNdis_StatusMediaConnect | NDIS Status Media Connect |
| MSNdis_StatusMediaDisconnect | NDIS Status Media Disconnect |
| MSNdis_StatusMediaSpecificIndication | NDIS Status Media Specific Indication |
| MSNdis_StatusProtocolBind | NDIS Protocol Bind Notification |
| MSNdis_StatusProtocolUnbind | NDIS Protocol Unbind Notification |
| MSNdis_StatusResetEnd | NDIS Status Reset End |
| MSNdis_StatusResetStart | NDIS Status Reset Start |
| MSNdis_TransmitBlockSize | NDIS Transmit Block Size |
| MSNdis_TransmitBufferSpace | NDIS Transmit Buffer Space |
| MSNdis_TransmitsError | NDIS Transmit Errors |
| MSNdis_TransmitsOk | NDIS Transmits OK |
| MSNdis_VendorDescription | NDIS Vendor Description |
| MSNdis_VendorDriverVersion | NDIS Vendor's Driver Version |
| MSNdis_VendorID | NDIS Vendor ID |
| MSNdis_VlanIdentifier | NDIS VLAN Identifier |
| MSPower_DeviceEnable | The control sets whether the device should dynamically power on and off while the system is working. |
| MSPower_DeviceWakeEnable | This control indicates whether the device should be configured to wake a sleeping system. |
| MSRedbook_DriverInformation | Digital Audio Filter Driver Information (redbook) |
| MSRedbook_Performance | Digital Audio Filter Driver Performance Data (redbook) |
| MSSerial_CommInfo | Serial Communications Information |
| MSSerial_CommProperties | Communication properties for serial port |
| MSSerial_HardwareConfiguration | Hardware configuration for serial port |
| MSSerial_PerformargeInformation | Performance information for serial port |
| MSSerial_PortName | Serial Port Name |
| MSSmBios_RawSMBiosTables | Raw SMBIOS Tables |
| MSSmBios_SMBiosEventlog | Raw SMBIOS Eventlog |
| MSSmBios_Sysid1394List | List Of 1394 SYSIDS |
| MSSmBios_SysidUUIDList | List of UUID SYSIDS |
| MSTapeDriveParam | Tape Drive Parameters |
| MSTapeDriveProblemEvent | Tape Drive Problem Warning |
| MSTapeMediaCapacity | Tape Media Capacity |
| MSTapeProblemDeviceError | Device Errors |
| MSTape ProblemIOError | IO Read Write Errors |
| MSTapeSymbolicName | Tape Symbolic Name |
| ProcessorCStateEvent | Processor CStates Event |
| ProcessorMethods | Methods to alter Processor Performance States |
| ProcessorPerformance | Processor Information |
| ProcessorPerfStateEvent | Processor Performance State Change Event |
| ProoessorStatus | Processor Performance Information |
| ProoessorTransitionEvent | Processor Transition Event |
Since an event provider is also available, an extrinsic event class can be used in the WQL event queries. The event class is called WMIEvent and is used as a parent class to define a collection of extrinsic event classes (see Figure 5.15).
Figure 5.15: The WMIEvent extrinsic event class.
To give a first example of the WDM providers classes use, we can reuse the GetCollectionOfInstances.wsf script (see Sample 1.5, "Listing all instances of a class with their properties formatted") and request all instances of the MSDiskDriver_Geometry class.
C:\>GetCollectionOfInstances.wsf MSDiskDriver_Geometry /Namespace:Root\WMI Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996–2001. All rights reserved. Active: .................................. TRUE BytesPerSector: .......................... 512 Cylinders: ............................... 5169 *InstanceName: ........................... IDE\DiskMAXTOR_6L040J2_..._A93.0500\3631... 2020202020_0 MediaType: ............................... 12 SectorsPerTrack: ......................... 63 TracksPerCylinder: ....................... 240
Actually, the MSDiskDriver_Geometry class exposes a subset of the information retrieved by the Win32_DiskDrive class.
As a second example, we can also detect network cable disconnections/ reconnections. To do so, we must work with the MSNdis_StatusMediaDisconnect class, which is a subclass of the WMIEvent extrinsic event class. If we reuse Sample 6.17 ("A generic script for asynchronous event notification") in the appendix, when a network cable disconnection occurs, the script returns an event notification, as shown in Figure 5.16.
Figure 5.16: Detecting network cable disconnections with the MSNdis_StatusMediaDisconnect extrinsic event class.
By requesting instances of the MSNdis_MediaConnectStatus class, it is possible to retrieve the state of all network connections available in the system.
C:\>GetCollectionOfInstances.wsf MSNdis_MediaConnectStatus /Namespace:Root\WMI Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996–2001. All rights reserved. Active: .................................. TRUE *InstanceName: ........................... WAN Miniport (Network Monitor) NdisMediaConnectStatus: .................. 0 Active: .................................. TRUE *InstanceName: ........................... WAN Miniport (IP) NdisMediaConnectStatus: .................. 0 Active: .................................. TRUE *InstanceName: ........................... Intel(R) PRO/100 VM Network Connection NdisMediaConnectStatus: .................. 0
When the NdisMediaConnectStatus property is set to 0, the network is connected. When the property is set to 1, the network is disconnected.
EAN: 2147483647
Pages: 82