Managing Windows Networks Using Scripts – Part 4: Using Win32

If you would like to read the other parts in this article series please go to:

In the first two articles of this series we examined the basics of using Windows scripting to manage TCP/IP networking settings. In particular, we developed the following simple script to change the IP address of a network adapter:

Option Explicit
On Error Resume Next

Dim objWMIService
Dim objNetAdapter
Dim strComputer ‘ Can specify IP address or hostname or FQDN
Dim strAddress ‘Contains the new IP address
Dim arrIPAddress
Dim arrSubnetMask
Dim colNetAdapters
Dim errEnableStatic

‘Check for missing arguments

If WScript.Arguments.Count = 0 Then
Wscript.Echo “Usage: ChangeIPAddress.vbs new_IP_address”
WScript.Quit
End If

strComputer = “.”
strAddress = Wscript.Arguments.Item(0)
arrIPAddress = Array(strAddress)
arrSubnetMask = Array(“255.255.255.0”)
Set objWMIService = GetObject(“winmgmts:\\” & strComputer & “\root\cimv2”)
Set colNetAdapters = objWMIService.ExecQuery(“Select * from Win32_NetworkAdapterConfiguration where IPEnabled=TRUE”)
For Each objNetAdapter in colNetAdapters
errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)
Next

‘Display result or error code

If errEnableStatic=0 Then
Wscript.Echo “Adapter’s IP address has been successfully changed to ” & strAddress
Else
Wscript.Echo “Changing the adapter’s address was not successful. Error code ” & errEnableStatic
End If

Pre-order your copy of the Microsoft Windows Vista Resource Kit today!

This above script changes the IP address of a network adapter by using Win32_NetworkAdapterConfiguration, which is one of the most useful WMI classes for managing TCP/IP networking configuration of Windows-based systems. In our third article we took a brief detour into “WMI Land” to learn more about WMI namespaces, providers and classes so we could better understand the following cryptic line that lies at the heart of this script:

Set objWMIService = GetObject(“winmgmts:\\” & strComputer & “\root\cimv2”)

If you recall, what this line does is to connect you to the root\cimv2 namespace on the local computer by defining an object named objWMIService and setting it equal to the handle returned by the GetObject method. And of course, once you’re connected to this namespace, you can collect information from it.

In today’s article however, the line we want to focus on is the line that follows this one in our script and which makes use of the Win32_NetworkAdapterConfiguration class:

Set colNetAdapters = objWMIService.ExecQuery(“Select * from Win32_NetworkAdapterConfiguration where IPEnabled=TRUE”)

If you recall again, what this second line does is call the ExecQuery method for the objWMIService object which we instantiated in the first line. A SELECT statement is passed to this method as an argument, and the collection of all network adapter configurations on the system that have TCP/IP bound and enabled on the adapter is returned and is assigned to the variable colNetAdapters. Once we have this collection, we can loop through it using a For Each…Next loop. Remember that you always have to loop through collections even if they have only one object in them.

The question we want to pose today is this: What else can we do with the Win32_NetworkAdapterConfiguration class?

Using Properties and Methods of Win32_NetworkAdapterConfiguration

Recall that properties represent information you can retrieve from a system using WMI. The more properties a WMI class has, the more information you can get out of it. It turns out that the Win32_NetworkAdapterConfiguration class actually has 61 different properties, some of them unique and others inherited from other classes. You can find a complete list of properties for the Win32_NetworkAdapterConfiguration class on the MSDN page for this class, which can be found here. When you’re trying to learn how to do WMI scripting so you can manage Windows networks using scripts, it’s important to become familiar with WMI information like this on MSDN, and Figure 1 below shows some of the properties of this class as listed on this page:

Figure 1: Properties of Win32_NetworkAdapterConfiguration class

In the figure above I’ve clicked on the link for the boolean property IPEnabled, which we used in our script to identify all network adapters on our system that have TCP/IP bound and enabled on them. We did this by passing the following SQL query as an argument to the objWMIService.ExecQuery method:

Select * from Win32_NetworkAdapterConfiguration where IPEnabled=TRUE

Right away we can see how we can extend the functionality of our script by querying for other properties of this class. For example, if we wanted to select all network adapters on our system that have DHCP enabled on them, we simply need to change our SELECT statement to this:

Select * from Win32_NetworkAdapterConfiguration where DHCPEnabled=TRUE

How do we know this? Because this information can be found on the same MSDN page as shown in Figure 2:

Figure 2: The DHCPEnabled property of the Win32_NetworkAdapterConfiguration class

What about the methods for this class? Recall that methods are things you call so you can perform different actions using WMI. It turns out that Win32_NetworkAdapterConfiguraiton has lots of methods too, in fact 41 methods in all. You can find the methods for this class listed on the same page below the properties, as shown in Figure 3:

Figure 3: Methods of the Win32_NetworkAdapterConfiguration class

Let’s go back for a moment to the following key section of our script:

Set objWMIService = GetObject(“winmgmts:\\” & strComputer & “\root\cimv2”)
Set colNetAdapters = objWMIService.ExecQuery(“Select * from Win32_NetworkAdapterConfiguration where IPEnabled=TRUE”)
For Each objNetAdapter in colNetAdapters
errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)
Next

First we used the IPEnabled property of the Win32_NetworkAdapterConfiguration class to return the collection network adapters that have TCP/IP bound and enabled on them. Then we called the EnableStatic method of this same class to change the IP address and subnet mask of these network adapters using the array variables arrIPAddress and arrSubnetMask, which were defined previously in our script. How did we know we had to pass two variables as arguments for this method? Well, by clicking on the EnableStatic link in Figure 3 above, the MSDN page shown in Figure 4 is displayed, which gives us information on how to use this class:

Figure 4: Detailed information concerning the EnableStatic method of the Win32_NetworkAdapterConfiguration class

Note that not only does this MSDN page give us the syntax of how to call this class, it also gives us the return value and how to interpret different error conditions that could arise. That’s why we used the error variable in the following line of our script:

errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)

And it’s also why we included the following lines in our script to report the error code should an error condition arise when our script is run:

Once again, we can see how we can extend the functionality of our script, this time by calling other methods of this class. For example, let’s say we wanted to disable NetBIOS over TCP/IP (NetBT) on all our network adapters that have TCP/IP bound and enabled on them. After skimming through the MSDN page for the Win32_NetworkAdapterClass page, we find a method called SetTcpNetbios that seems to fit the bill for this (see Figure 5):

Figure 5: The SetTcpipNetbios method of the Win32_NetworkAdapterConfiguration class

Clicking on the link for this method opens a page with information on how to use it (Figure 6):

Figure 6: Detailed information concerning the SetTcpipNetbios method

We can see that if we want to disable NetBT on our adapters, all we need to do is change the following line in our script:

errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)

to this:

errEnableStatic = objNetAdapter.SetTcpipNetbios(2)

After making this change and cleaning up our script by removing variables that are no longer needed and renaming others, we now have the following script that can be used to disable NetBT on all network adapters that have TCP/IP bound and enabled on them:

‘=========================
‘ NAME: DisableNetbios.vbs
‘
‘AUTHOR: Mitch Tulloch
‘DATE: December 2006
‘
‘ARGUMENTS:
‘1. None
‘=========================-

Option Explicit
On Error Resume Next

Dim objWMIService
Dim objNetAdapter
Dim strComputer ‘ Can specify IP address or hostname or FQDN
Dim colNetAdapters
Dim errDisableNetbios

strComputer = “.”
Set objWMIService = GetObject(“winmgmts:\\” & strComputer & “\root\cimv2”)
Set colNetAdapters = objWMIService.ExecQuery(“Select * from Win32_NetworkAdapterConfiguration where IPEnabled=TRUE”)
For Each objNetAdapter in colNetAdapters
errEnableStatic = objNetAdapter.SetTcpipNetbios(2)
Next

‘Display result or error code

If errDisableNetbios=0 Then
Wscript.Echo “NetBIOS has been successfully disabled on the adapters”
Else
Wscript.Echo “Disabling NetBIOS was not successful. Error code ” & errDisableNetbios
End If

Let’s see if it works. Figure 7 shows the WINS tab of the Advanced TCP/IP Properties for Local Area Connection on a Windows Server 2003 machine:

Figure 7: NetBIOS over TCP/IP settings on a Windows Server 2003 machine

Note that the current NetBT setting for this machine is “Default” which corresponds to a value of 0 for the SetTcpipNetbios method (see Figure 6 previously). Let’s copy our new script to Notepad (make sure Word Wrap is turned off) and save it as DisableNetbios.vbs. Then we’ll run it on our server in a command prompt window using cscript (Figure 8):

Figure 8: Disabling NetBIOS over TCP/IP using a script

Now let’s see if it worked. We need to close our TCP/IP properties pages and re-open them to refresh the NetBT setting in the GUI, which now looks like this (Figure 9):

Figure 9: NetBT has been successfully disabled

Conclusion

The best way to learn Windows scripting is by actually trying it out, so here are a couple of exercises you can try on your own to reinforce what you’ve learned in this article:

Modify the script so it can take arguments i.e. type DisableNetbios.vbs 1 to enable NetBT, DisableNetbios.vbs 2 to disable it, and DisableNetbios.vbs 0 to return it to its default setting of using DHCP to determine whether NetBT is enabled or disabled for the adapter.
Modify the SELECT statement in the script to select network adapters based on some other property of the Win32_NetworkAdapterConfiguration class, and modify it further to call some different method of this class to perform some other action on the TCP/IP configuration of the network adapters.
Browse MSDN to learn about other WMI classes that look like they might be useful to you for scripting different Windows administration tasks.

If you would like to read the other parts in this article series please go to: