Part 7: Scripting Other Network Protocols

  • Article

This section demonstrates how to use WMI to script the management of a variety of TCP/IP and related protocols on clients: TCP/IP filtering; ARP, IP, and TCP settings relating to routing; Internetwork Packet Exchange (IPX) settings; and enumeration of network protocols running on hosts. The sample scripts demonstrate more properties and methods of the Win32_NetworkAdapterConfiguration class and introduce a new WMI class, Win32_NetworkProtocol.

This section provides scripting steps and sample scripts for these protocol-related tasks:

  • Managing TCP/IP filtering settings.

  • Managing other TCP/IP settings.

    This includes subsections about managing and retrieving ARP settings, TCP settings, and IP packet settings.

  • Managing IPX.

  • Enumerating the network protocols on a computer.

On This Page

Managing TCP/IP Filtering Settings
Managing Other TCP/IP Settings
Managing IPX
Enumerating the Network Protocols on a Computer
Tools for Scripting Other Network Protocols

Managing TCP/IP Filtering Settings

As network security threats, such as viruses and worms, have gained notoriety, Internet Protocol security (IPSec) has achieved increasing acceptance as an integrated set of interoperable, cryptographically-based security services for traffic in the network layer between TCP/IP nodes. For information about the base architecture of IPSec, see Internet Engineering Task Force RFC 2401, "Security Architecture for the Internet Protocol," at https://go.microsoft.com/fwlink/?LinkId=24797.

WMI enables scripting the retrieval and configuration of TCP/IP client settings relating to one aspect of IPSec, TCP/IP filtering, through several properties and methods of the Win32_NetworkAdapterConfiguration class.

The first step in implementing TCP/IP filtering with WMI is to turn on filtering. To do this, you set the IPFilterSecurityEnabled property to True by using the EnableIPFilterSec method. After TCP/IP filtering is enabled, you can specify the TCP and User Datagram Protocol (UDP) ports to filter, and permit or exclude specific protocols over IP. For more information about TCP/IP filtering, see the WMI SDK topics about the EnableIPSec and EnableIPFilterSec methods of Win32_NetworkAdapterConfiguration at https://go.microsoft.com/fwlink/?LinkId=29991.

caution.gif  Caution
Before changing these settings, make sure that the new configuration is consistent with your network's implementation of TCP/IP filtering, IPSec, and overall network security. Always test such changes on a test network before making them in a production environment.

Note that the two TCP/IP filtering methods, EnableIPSec and EnableIPFilterSec, do not follow the division of functionality between "IP security" and "TCP/IP filtering," the two settings listed on the Options tab of the Advanced TCP/IP Settings dialog box in Windows 2000. In Windows XP and Windows Server 2003, only one option, "TCP/IP filtering," is listed on the Options tab, as Figure 13 illustrates.

07ATNC01.gif

Figure 13   Managing TCP/IP Filtering by Using the Windows Interface

This section first presents two sample scripts that show you how to use these methods separately. Then the section provides a third script that combines the methods to show how to enable TCP/IP filtering and specify port and protocol filtering within the same script, as administrators might often want to do. The script first tests whether TCP/IP filtering is enabled, and if it is not, enables it. It then sets filters that grant access for only the specified TCP and UDP ports, and IP protocols.

Table 25 describes the TCP/IP filtering properties for the Win32_NetworkAdapterConfiguration class.

Table 25   TCP/IP Filtering Properties for the Win32_NetworkAdapterConfiguration Class

Property

Type

Description

IPFilterSecurityEnabled

Boolean

If TRUE, IP port security is enabled globally across all IP-bound network adapters and the security values associated with individual network adapters are in effect. This property is used in conjunction with IPSecPermitTCPPorts, IPSecPermitUDPPorts, and IPSecPermitIPProtocols. If FALSE, IP filter security is disabled across all network adapters and allows all port and protocol traffic to flow unfiltered.

IPSecPermitIPProtocols

String array

Array of the protocols permitted to run over the IP. The list of protocols is defined using the EnableIPSec method. The list will either be empty or contain numeric values. A numeric value of 0 (zero) indicates access permission is granted for all protocols. An empty string indicates that no protocols are permitted to run when IPFilterSecurityEnabled is TRUE.

IPSecPermitTCPPorts

String array

Array of the ports that will be granted access permission for TCP. The list of protocols is defined using the EnableIPSec method. The list will either be empty or contain numeric values. A numeric value of 0 (zero) indicates access permission is granted for all ports. An empty string indicates that no ports are granted access permission when IPFilterSecurityEnabled is TRUE.

IPSecPermitUDPPorts

String array

Array of the ports that will be granted User Datagram Protocol (UDP) access permission. The list of protocols is defined using the EnableIPSec method. The list will either be empty or contain numeric values. A numeric value of 0 (zero) indicates access permission is granted for all ports. An empty string indicates that no ports are granted access permission when IPFilterSecurityEnabled is TRUE.

All the properties in the previous table are read-only.

Table 26 outlines the TCP/IP filtering methods and parameters for Win32_NetworkAdapterConfiguration.

Table 26   Win32_NetworkAdapterConfiguration TCP/IP Filtering Methods

Method

Parameters

Description

EnableIPFilterSec

IPFilterSecurityEnabled - Boolean

Static method. Enables TCP/IP filtering globally across all IP-bound network adapters. With security enabled, the operational security characteristics for any one network adapter can be controlled by using the network adapter-specific EnableIPSec method.

EnableIPSec

IPSecPermitTCPPorts – string array

IPSecPermitUDPPorts – string array

IPSecPermitIPProtocols – string array

Enables TCP/IP filtering on a TCP/IP-enabled network adapter. Ports are secured only when the IPFilterSecurityEnabled property in Win32_NetworkAdapterConfiguration is True.

All the methods in the previous table return a positive integer:

  • 0 indicates successful completion.

  • 1 indicates successful completion with reboot required.

  • Numbers greater than 1 indicate that a problem was encountered and the method could not complete. The WMI SDK lists the meanings of return values for these methods.

The Ipseccmd.exe command-line tool and the netsh ipsec command provide more extensive functionality for working with many aspects of IPSec.

Displaying TCP/IP Filtering Settings

To retrieve TCP/IP filtering settings, Win32_NetworkAdapterConfiguration provides several properties that are network adapter-specific. IPFilterSecurityEnabled, however, is a global property that applies to all IP-enabled network adapters. Note that IPFilterSecurityEnabled has replaced the obsolete IPPortSecurityEnabled.

The properties IPSecPermitIPProtocols, IPSecPermitTCPPorts, and IPSecPermitUDPPorts all return arrays of strings representing the ports or protocols that have been granted access permission. For each, "0" indicates that access permission is granted for all protocols or ports, while an empty string indicates that access permission is not granted for any ports.

Scripting Steps

Listing 44 displays TCP/IP filtering settings on all installed network adapters by using the properties of Win32_Network AdapterConfiguration.

  1. Create a variable and assign the name of a computer to it. For the local computer, simply specify "." as the computer name. To run this script remotely, specify the name of an accessible remote computer on your network on which you have administrative privileges. The name can be in the form of either a host name or an IP address.

  2. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  3. Use the ExecQuery method to query the Win32_NetworkAdapterConfiguration class, filtering the WQL query with “WHERE IPEnabled = True.”

    This returns a collection consisting of all the network adapter configurations on the computer for which IP is enabled.

  4. For each network adapter configuration in the collection, display the index number, description, and value for the IPFilterSecurityEnabled property.

  5. If the IPSecPermitIPProtocols, IPSecPermitTCPPorts, and IPSecPermitUDPPorts properties are not null, iterate through the arrays they return and display their values.

Listing 44   Ipfiltersettings.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


On Error Resume Next
 
strComputer = "."
 
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
 
For Each objNicConfig in colNicConfig
  WScript.Echo VbCrLf & "Network Adapter " & objNicConfig.Index & _
   VbCrLf & "  " & objNicConfig.Description
  WScript.Echo "    IP Filter Security Enabled: " & _
   objNicConfig.IPFilterSecurityEnabled
  WScript.Echo "    Protocols Permitted over IP:"
  If Not IsNull(objNicConfig.IPSecPermitIPProtocols) Then
    For Each strIPProtocol In objNicConfig.IPSecPermitIPProtocols
      WScript.Echo "      " & strIPProtocol
    Next
  End If
  WScript.Echo "    TCP Ports Permitted:"
  If Not IsNull(objNicConfig.IPSecPermitTCPPorts) Then
    For Each strTCPPort In objNicConfig.IPSecPermitTCPPorts
      WScript.Echo "      " & strTCPPort
    Next
  End If
  WScript.Echo "    UDPPorts Permitted:"
  If Not IsNull(objNicConfig.IPSecPermitUDPPorts) Then
    For Each strUDPPort In objNicConfig.IPSecPermitUDPPorts
      WScript.Echo "      " & strUDPPort
    Next
  End If
Next

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>ipfiltersettings.vbs

 

Network Adapter 1

  3Com 3C920 Integrated Fast Ethernet Controller (3C905C-TX Compatible) - Packet

Scheduler Miniport

    IP Filter Security Enabled: False

    Protocols Permitted over IP:

      0

    TCP Ports Permitted:

      0

    UDPPorts Permitted:

      0

Enabling TCP/IP Filtering by Using EnableIPFilterSec

The class static method used in this script, EnableIPFilterSec, enables TCP/IP filtering globally across all IP-enabled network adapters. After you enable TCP/IP filtering on all network adapters, you can configure specific TCP/IP filtering settings for each one with the EnableIPSec method.

EnableIPFilterSec is a class static method that applies to all instances of the Win32_NetworkAdapterConfiguration class, which is to say, all network adapters. This means that you can use the Get() method of the SwbemServices object to get the Win32_NetworkAdapterConfiguration class, rather than use the ExecQuery() method to get the instances of the class. Instead of simply calling the method without parameters, like you do with EnableDHCP, you have to pass it a Boolean value (True or False) for the IPFilterSecurityEnabled property.

If your script calls only static methods, you can use more compact ways of binding to the Win32_NetworkAdapterConfiguration class. For example, you might use either of the following lines:

Set objNicConfig = GetObject("winmgmts:\\" & strComputer & _
 "\root\cimv2:Win32_NetworkAdapterConfiguration")



Set objNicConfig = GetObject("winmgmts:").Get _
 ("Win32_NetworkAdapterConfiguration")

Scripting Steps

caution.gif  Caution
This script may make changes in your computer configuration. Run it only on a test computer and note the settings involved before running it.

Listing 45 enables IP filter security for all installed network adapters by using the EnableIPFilterSec method of Win32_Network AdapterConfiguration. This method sets the IPFilterSecurityEnabled property to True. IP filter security is called TCP/IP Filtering on the Options tab of the Advanced TCP/IP dialog box.

  1. Create a variable to specify the computer name.

  2. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  3. Use the static Get method of the SWbemServices object to get an SWbemObject representing the Win32_NetworkAdapterConfiguration class.

    Changes made to this object apply to all network adapters on the computer.

  4. Call the EnableIPFilterSec static method of Win32_NetworkAdapterConfiguration, passing it a Boolean parameter of True.

  5. Check the value returned by the method, and display a success or error message.

Listing 45   Ipfilter-enableipfilter.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20


On Error Resume Next
 
strComputer = "."
 
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set objNicConfig = objWMIService.Get("Win32_NetworkAdapterConfiguration")
 
If Not objNicConfig.IPFilterSecurityEnabled Then
  intFilterReturn = objNicConfig.EnableIPFilterSec(True)
  If intFilterReturn = 0 Then
    WScript.Echo "IP Filtering enabled for all network adapters."
  ElseIf intFilterReturn = 1 Then
    WScript.Echo "IP Filtering enabled for all network adapters." & _
     VbCrLf & "Must reboot for changes to take effect."
  Else
    WScript.Echo "Unable to enable IP Filtering."
  End If
Else
  WScript.Echo "IP Filtering already enabled."
End If

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>ipfilter-enableipfilter.vbs

IP Filter Security Enabled:

IP Filtering enabled for all network adapters.

Must reboot for changes to take effect.

Implementing TCP/IP Filtering by Using EnableIPSec

After you enable TCP/IP filtering by using EnableIPFilterSec, you can use the EnableIPSec method to grant access permission to TCP and UDP traffic on specific ports and deny access on others. You can also permit or exclude protocols to run over IP. The EnableIPSec method makes these specific security choices for each network adapter.

Note that the EnableIPSec and EnableIPFilterSec methods reverse the functionality of "IP security" and "TCP/IP filtering," the two settings listed in the Advanced TCP/IP Settings dialog box in Windows 2000. In Windows XP and Windows Server 2003, the two settings are merged into one option, TCP/IP filtering, on the Options tab.

The Properties button on the Options tab enables you to open the TCP/IP Filtering dialog box, which includes a check box for "Enable TCP/IP Filtering (All adapters)" and separate settings for TCP ports, UDP ports, and IP protocols. For each of these options, you can choose either "Permit All" or "Permit Only," which enables you to specify the ports or protocols to be permitted.

Scripting Steps

Listing 46 enables IP filter security on specific network adapters by using the EnableIPSec method. This script grants access permission to all TCP, UDP, and IP ports.

important.gif  Important
Before running this script, you must set the IPFilterSecurityEnabled property to True by using the EnableIPFilterSec method of Win32_Network AdapterConfiguration. For information about performing this step, see “Enabling TCP/IP Filtering by Using EnableIPFilterSec” earlier in this paper.

For the three parameters of EnableIPSec, IPSecPermitIPProtocols, IPSecPermitTCPPorts, and IPSecPermitUDPPorts, a value of 0 indicates that access permission is granted for all protocols or ports and a null value (an empty array) indicates that access permission is not granted for any protocols or ports. Otherwise, IPSecPermitTCPPorts and IPSecPermitUDPPorts must be arrays of strings representing the ports to be granted access; IPSecPermitIPProtocols must be an array of strings representing the permitted protocols.

caution.gif  Caution
This script may make changes in your computer configuration. Run it only on a test computer and note the settings involved before running it.

  1. Define a constant for allowing all ports and protocols.

  2. Create a variable to specify the computer name.

  3. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  4. Use the ExecQuery method to query the Win32_NetworkAdapterConfiguration class, filtering the WQL query with “WHERE IPEnabled = True.”

    This returns a collection consisting of all the network adapter configurations on the computer for which IP is enabled.

  5. For each network adapter configuration in the collection, perform the following tasks.

  6. Assign the ALLOW_ALL constant to arrays of permitted TCP ports, permitted UDP ports, and permitted IP protocols, to be passed as parameters.

    The script can be modified to specify only certain ports and protocols.

  7. Call the EnableIPSec method of Win32_NetworkAdapterConfiguration, passing it the arrays of permitted TCP ports, permitted UDP ports, and permitted IP protocols.

  8. Check the value returned by the method, and display a success or error message.

Listing 46   Ipfilter-enableipsec.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


On Error Resume Next
 
Const ALLOW_ALL = 0
arrPermittedTCPPorts = Array(ALLOW_ALL)
arrPermittedUDPPorts = Array(ALLOW_ALL)
arrPermittedIPProtocols = Array(ALLOW_ALL)
 
strComputer = "."
 
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
 
For Each objNicConfig in colNicConfig
  WScript.Echo VbCrLf & "  Network Adapter " & objNicConfig.Index
  If objNicConfig.IPFilterSecurityEnabled Then
    intIPSecReturn = objNicConfig.EnableIPSec(arrPermittedTCPPorts, _
     arrPermittedUDPPorts, arrPermittedIPProtocols)
    If intIPSecReturn = 0 Then
      WScript.Echo "  IP Filtering enabled for specified ports and protocols."
    ElseIf intIPSecReturn = 1 Then
      WScript.Echo "  IP Filtering enabled for specified ports and protocols." _
       & VbCrLf & "  Must reboot for changes to take effect."
    Else
      WScript.Echo "  Unable to enable IP Filtering for " & _
       "specified ports and protocols."
    End If
  Else
    WScript.Echo "  IP Filtering not enabled. Must enable before " & _
     "specifying port and protocols."
  End If
Next

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>ipfilter-enableipsec.vbs

 

  Network Adapter 1

  IP Filtering enabled for specified ports and protocols.

  Must reboot for changes to take effect.

Enabling and Implementing TCP/IP Filtering in a Single Script

This script combines techniques from the previous two sections to show how to combine the EnableIPFilterSec and EnableIPSec methods to enable TCP/IP filtering and configure specifics on all network adapters.

The script first tests for whether TCP/IP filtering is enabled and, if not, it calls EnableIPFilterSec. It then sets permitted TCP and UDP ports, and IP protocols.

For simplicity, this script is designed to set the same EnableIPSec parameters for each network adapter; a more complex script could set different settings for specific network adapters.

The script defines two constants that will be passed as parameters to EnableIPSec.

  • The value of ALLOW_ALL is a string containing the number 0, which allows all ports or protocols. This constant is passed to EnableIPSec as the parameter for permitted UDP ports.

  • The value of ALLOW_NONE is an empty string (""), which denies permission to all ports or protocols. This constant is passed to EnableIPSec as the parameter for permitted IP protocols.

For permitted TCP ports, the script directly passes two literal string values, “80” and “443,” to the method.

Scripting Steps

caution.gif  Caution
This script may make changes in your computer configuration. Run it only on a test computer and note the settings involved before running it.

  1. Define constants for allowing all ports and protocols (0) and for allowing none (an empty string).

  2. Create a constant for the value that will allow all traffic and a variable to specify the computer name.

  3. Set the Boolean variable representing the state of the IPFilterSecurityEnabled property to False.

  4. Assign ports 80 and 443 to the array of permitted TCP ports.

  5. Assign the ALLOW_NONE constant to the array of permitted UDP ports.

  6. Assign the ALLOW_ALL constant to the arrays of permitted IP protocols.

  7. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  8. Use the ExecQuery method to query the Win32_NetworkAdapterConfiguration class, filtering the WQL query with “WHERE IPEnabled = True.”

    This returns a collection consisting of all the network adapter configurations on the computer for which IP is enabled.

  9. Iterate through the collection of network adapters, displaying current TCP/IP filtering settings.

  10. If the IPFilterSecurityEnabled property is set to False, call the static Get method of the SWbemServices object to get an SWbemObject representing the Win32_NetworkAdapterConfiguration class.

    Changes made to this object apply to all network adapters on the computer.

  11. Call the EnableIPFilterSec method of Win32_NetworkAdapterConfiguration on the class object reference, passing it a parameter of True.

  12. Check the value returned by the method, and display a success or error message.

  13. Requery the Win32_NetworkAdapterConfiguration class with the ExecQuery method, filtering the WQL query with “WHERE IPEnabled = True.”

  14. Iterate through the collection of network adapters again, calling the EnableIPSec method of Win32_NetworkAdapterConfiguration on each, and passing it the arrays of permitted TCP ports, permitted UDP ports, and permitted IP protocols.

  15. Check the value returned by the method, and display a success or error message.

  16. Requery the Win32_NetworkAdapterConfiguration class with the ExecQuery method, filtering the WQL query with “WHERE IPEnabled = True.”

  17. Iterate through the collection of network adapters, displaying TCP/IP filtering settings including any changes.

Listing 47   Ipfilter-enable.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109


On Error Resume Next
 
Const ALLOW_ALL = "0"
Const ALLOW_NONE = ""
 
strComputer = "."
blnIPFilterSecurityEnabled = "False"
arrPermittedTCPPorts = Array("80", "443")
arrPermittedUDPPorts = Array(ALLOW_NONE)
arrPermittedIPProtocols = Array(ALLOW_ALL)
 
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
WScript.Echo VbCrLf & "Settings Before Enabling IP Filtering"
 
For Each objNicConfig in colNicConfig
  blnIPFilterSecurityEnabled = objNicConfig.IPFilterSecurityEnabled
  WScript.Echo VbCrLf & "  Network Adapter " & objNicConfig.Index & VbCrLf & _
   "    IP Filtering Enabled: " & blnIPFilterSecurityEnabled
  WScript.Echo "    TCP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitTCPPorts) Then
    For Each strTCPPort In objNicConfig.IPSecPermitTCPPorts
      WScript.Echo "      " & strTCPPort
    Next
  End If
  WScript.Echo "    UDP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitUDPPorts) Then
    For Each strUDPPort In objNicConfig.IPSecPermitUDPPorts
      WScript.Echo "      " & strUDPPort
    Next
  End If
  WScript.Echo "    IP Protocols:"
  If Not IsNull(objNicConfig.IPSecPermitIPProtocols) Then
    For Each strIPProtocol In objNicConfig.IPSecPermitIPProtocols
      WScript.Echo "      " & strIPProtocol
    Next
  End If
Next
 
If blnIPFilterSecurityEnabled = False Then
  WScript.Echo VbCrLf & "Enabling IP Filtering ..."
  Set objAllNicsConfig = objWMIService.Get("Win32_NetworkAdapterConfiguration")
  intFilterReturn = objAllNicsConfig.EnableIPFilterSec(True)
  If intFilterReturn = 0 Then
    WScript.Echo "  IP Filtering enabled for all network adapters."
    SpecifyFilters
  ElseIf intFilterReturn = 1 Then
    WScript.Echo "  IP Filtering enabled for all network adapters." _
     & VbCrLf & "  Must reboot for changes to take effect."
    SpecifyFilters
  Else
    WScript.Echo "  Unable to enable IP Filtering."
  End If
Else
  WScript.Echo VbCrLf & "IP Filtering already enabled for all network adapters."
  SpecifyFilters
End If
 
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
WScript.Echo VbCrLf & "Settings After Enabling IP Filtering"
 
For Each objNicConfig in colNicConfig
  WScript.Echo VbCrLf & "  Network Adapter " & objNicConfig.Index & VbCrLf & _
   "    IP Filtering Enabled: " & objNicConfig.IPFilterSecurityEnabled
  WScript.Echo "    TCP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitTCPPorts) Then
    For Each strTCPPort In objNicConfig.IPSecPermitTCPPorts
      WScript.Echo "      " & strTCPPort
    Next
  End If
  WScript.Echo "    UDP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitUDPPorts) Then
    For Each strUDPPort In objNicConfig.IPSecPermitUDPPorts
      WScript.Echo "      " & strUDPPort
    Next
  End If
  WScript.Echo "    IP Protocols:"
  If Not IsNull(objNicConfig.IPSecPermitIPProtocols) Then
    For Each strIPProtocol In objNicConfig.IPSecPermitIPProtocols
      WScript.Echo "      " & strIPProtocol
    Next
  End If
Next
 
'******************************************************************************
 
Sub SpecifyFilters
 
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
For Each objNicConfig in colNicConfig
  intIPSecReturn = objNicConfig.EnableIPSec(arrPermittedTCPPorts, _
   arrPermittedUDPPorts, arrPermittedIPProtocols)
  If intIPSecReturn = 0 Then
    WScript.Echo "  Filters enabled on " & _
     objNicConfig.Index & " for specified ports and protocols."
  ElseIf intIPSecReturn = 1 Then
    WScript.Echo "  Filters enabled on " & _
     objNicConfig.Index & " for specified ports and protocols." _
     & VbCrLf & "  Must reboot for changes to take effect."
  Else
    WScript.Echo "  Unable to enable filters on " & _
     objNicConfig.Index & " for specified ports and protocols."
  End If
Next
 
End Sub

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>ipfilter-enable.vbs

 

Settings Before Enabling IP Filtering

 

  Network Adapter 1

    IP Filtering Enabled: False

    TCP Ports:

      0

    UDP Ports:

      0

    IP Protocols:

      0

 

Enabling IP Filtering ...

  IP Filtering enabled for all network adapters.

  Must reboot for changes to take effect.

  Filters enabled on 1 for specified ports and protocols.

  Must reboot for changes to take effect.

 

Settings After Enabling IP Filtering

 

  Network Adapter 1

    IP Filtering Enabled: True

    TCP Ports:

      80

      443

    UDP Ports:

    IP Protocols:

      0

Disabling TCP/IP Filtering

If you need to disable TCP/IP filtering on a network segment or another group of hosts, using scripting for those tasks on multiple computers can save administrative time. In certain situations on individual hosts, too, such as a laptop that is frequently moved between a network that uses TCP/IP filtering to one that does not, a script that disables TCP/IP filtering from the command prompt might be useful.

Scripting Steps

caution.gif  Caution
This script may make changes in your computer configuration. Run it only on a test computer and note the settings involved before running it.

Listing 48 disables TCP/IP filtering for each IP-enabled network adapter setting.

  1. Create a constant for the value that will allow all traffic and a variable to specify the computer name.

  2. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  3. Use the ExecQuery method to query the Win32_NetworkAdapterConfiguration class, filtering the WQL query with “WHERE IPEnabled = True.”

    This returns a collection consisting of all the network adapter configurations on the computer for which IP is enabled.

  4. For each network adapter configuration in the collection, perform the following tasks.

  5. Display the current TCP/IP filtering settings.

  6. Call the DisableIPSec method of Win32_NetworkAdapterConfiguration.

  7. Check the value returned by the method, and display a success or error message.

  8. Requery the Win32_NetworkAdapterConfiguration class with the ExecQuery method, filtering the WQL query with “WHERE IPEnabled = True.”

  9. Iterate through the collection of network adapters, displaying TCP/IP filtering settings including any changes.

Listing 48   Ipfilter-disable.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


On Error Resume Next
 
strComputer = "."
 
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
 
WScript.Echo VbCrLf & "IPSec and TCP/IP Filtering Settings"
 
For Each objNicConfig in colNicConfig
  WScript.Echo VbCrLf & "  Network Adapter " & objNicConfig.Index & _
   VbCrLf & "    IP Filtering Enabled: " & _
   objNicConfig.IPFilterSecurityEnabled
  WScript.Echo "    TCP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitTCPPorts) Then
        For Each strTCPPort In objNicConfig.IPSecPermitTCPPorts
            WScript.Echo "      " & strTCPPort
        Next
  End If
  WScript.Echo "    UDP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitUDPPorts) Then
    For Each strUDPPort In objNicConfig.IPSecPermitUDPPorts
      WScript.Echo "      " & strUDPPort
    Next
  End If
  WScript.Echo "    IP Protocols:"
  If Not IsNull(objNicConfig.IPSecPermitIPProtocols) Then
    For Each strIPProtocol In objNicConfig.IPSecPermitIPProtocols
      WScript.Echo "      " & strIPProtocol
    Next
  End If
  If objNicConfig.IPFilterSecurityEnabled Then
    intDisableReturn = objNicConfig.DisableIPSec
    If intDisableReturn = 0 Then
      WScript.Echo "    IP Filtering disabled."
    ElseIf intDisableReturn = 1 Then
      WScript.Echo "    IP Filtering disabled." & _
       VbCrLf & "    Must reboot for changes to take effect."
    Else
      WScript.Echo "    Unable to disable IP Filtering."
    End If
  Else
    WScript.Echo "    IP Filtering already disabled."
  End If
Next
 
Set colNicConfig = objWMIService.ExecQuery _
 ("Select * From Win32_NetworkAdapterConfiguration Where IPEnabled = True")
 
WScript.Echo VbCrLf & "Settings After Operation"
 
For Each objNicConfig in colNicConfig
  WScript.Echo VbCrLf & "  Network Adapter " & objNicConfig.Index & _
   VbCrLf & "    IP Filtering Enabled: " & _
   objNicConfig.IPFilterSecurityEnabled
  WScript.Echo "    TCP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitTCPPorts) Then
    For Each strTCPPort In objNicConfig.IPSecPermitTCPPorts
      WScript.Echo "      " & strTCPPort
    Next
  End If
  WScript.Echo "    UDP Ports:"
  If Not IsNull(objNicConfig.IPSecPermitUDPPorts) Then
    For Each strUDPPort In objNicConfig.IPSecPermitUDPPorts
      WScript.Echo "      " & strUDPPort
    Next
  End If
  WScript.Echo "    IP Protocols:"
  If Not IsNull(objNicConfig.IPSecPermitIPProtocols) Then
    For Each strIPProtocol In objNicConfig.IPSecPermitIPProtocols
      WScript.Echo "      " & strIPProtocol
    Next
  End If
Next

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>ipfilter-disable.vbs

 

IPSec and TCP/IP Filtering Settings

 

  Network Adapter 1

    IP Filtering Enabled: True

    TCP Ports:

      80

      443

    UDP Ports:

    IP Protocols:

      0

    IP Filtering disabled.

    Must reboot for changes to take effect.

 

Settings After Operation

 

  Network Adapter 1

    IP Filtering Enabled: True

    TCP Ports:

      0

    UDP Ports:

      0

    IP Protocols:

      0

Managing Other TCP/IP Settings

The Win32_NetworkAdapterConfiguration class exposes numerous other properties and methods relating to Address Resolution Protocol (ARP), Transmission Control Protocol (TCP), and Internet Protocol (IP) settings. Because most of these properties are primarily used to configure routing or for advanced network performance tuning, this paper does not cover them in much detail. However, they are listed in the following tables, and a script that displays the property settings for each protocol is shown below.

For each read-only property, there is a corresponding method to change it, but no example script is shown for the methods. If a computer is not configured for routing, these properties often return an empty value or Null.

For information about how to use a few of these settings to improve network performance, see the section “Performance Tuning for Networking” in “Performance Tuning Guidelines for Windows Server 2003” at https://go.microsoft.com/fwlink/?LinkId=24798.

Managing ARP Settings

Address Resolution Protocol (ARP) is the protocol that maps IP addresses to physical (MAC) addresses. Windows includes the command-line tool Arp.exe that can list and configure ARP cache entries.

Table 27 describes the Win32_NetworkAdapterConfiguration properties that work with ARP.

Table 27   ARP Properties for the Win32_NetworkAdapterConfiguration Class

Property

Type

Description

ArpAlwaysSourceRoute

Boolean

If True, TCP/IP transmits Address Resolution Protocol (ARP) queries with source routing enabled on Token Ring networks.

By default (False), ARP first queries without source routing, and then retries with source routing enabled if no reply is received. Source routing allows the routing of network packets across different types of networks.

ArpUseEtherSNAP

Boolean

If True, Ethernet packets follow the IEEE 802.3 Sub-Network Access Protocol (SNAP) encoding. Setting this parameter to 1 forces TCP/IP to transmit Ethernet packets by using 802.3 SNAP encoding.

By default (False), the stack transmits packets in DIX Ethernet format. Windows NT and Windows 2000 systems can receive both formats.

All the properties in the previous table are read-only.

Table 28 describes the Win32_NetworkAdapterConfiguration methods that work with ARP.

Table 28   ARP Methods for the Win32_NetworkAdapterConfiguration Class

Method

Parameters

Description

SetArpAlwaysSourceRoute

ArpAlwaysSourceRoute – Boolean

Static method. Sets the transmission of ARP queries by the TCP/IP.

If the parameter is True, TCP/IP is forced to transmit ARP queries with source routing enabled on Token Ring networks.

By default, the stack transmits ARP queries without source routing first, then retries with source routing enabled if no reply is received.

SetArpUseEtherSNAP

ArpUseEtherSNAP – Boolean

Static method. Enables TCP/IP to transmit Ethernet packets using 802.3 SNAP encoding.

If the parameter is True, Ethernet packets use 802.3 SNAP encoding.

By default, the stack transmits packets in Digital, Intel, Xerox (DIX) Ethernet format. It always receives both formats.

All the methods in the previous table return a positive integer:

  • 0 indicates successful completion.

  • 1 indicates successful completion with reboot required.

  • Numbers greater than 1 indicate that some problem was encountered and the method could not complete. The WMI SDK lists the meanings of return values for these methods.

Managing TCP Settings

Table 29 describes the Win32_NetworkAdapterConfiguration properties that work with TCP settings.

Table 29   Win32_NetworkAdapterConfiguration TCP Properties

Property

Type

Description

KeepAliveInterval

Uint32

Units: Milliseconds

Interval separating Keep Alive Retransmissions until a response is received. After a response is received, the delay until the next Keep Alive Transmission is again controlled by the value of KeepAliveTime. The connection will be aborted after the number of retransmissions specified by TcpMaxDataRetransmissions have gone unanswered. Default: 1000, Valid Range:
1–xFFFFFFFF.

KeepAliveTime

Uint32

Units: Milliseconds

Indicates how often the TCP attempts to verify that an idle connection is still intact by sending a Keep Alive Packet. A remote system that is reachable will acknowledge the keep alive transmission. Keep Alive packets are not sent by default. This feature may be enabled in a connection by an application. Default: 7,200,000 (two hours)

MTU

Uint32

Units: Bytes

Overrides the default Maximum Transmission Unit (MTU) for a network interface. The MTU is the maximum packet size (including the transport header) that the transport will transmit over the underlying network. The IP datagram can span multiple packets. The range of this value spans the minimum packet size (68) to the MTU supported by the underlying network.

PMTUBHDetectEnabled

Boolean

If TRUE, detection of black hole routers occurs while TCP discovers the path of the Maximum Transmission Unit. A black hole router does not return ICMP Destination Unreachable messages when it needs to fragment an IP datagram with the Don't Fragment bit set. TCP depends on receiving these messages to perform Path MTU Discovery. With this feature enabled, TCP will try to send segments without the Don't Fragment bit set if several retransmissions of a segment go unacknowledged. If the segment is acknowledged as a result, the MSS will be decreased and the Don't Fragment bit will be set in future packets on the connection. Enabling black hole detection increases the maximum number of retransmissions performed for a given segment. The default value of this property is FALSE.

PMTUDiscoveryEnabled

Boolean

If TRUE, the Maximum Transmission Unit (MTU) path is discovered over the path to a remote host. By discovering the MTU path and limiting TCP segments to this size, TCP can eliminate fragmentation at routers along the path that connect networks with different MTUs. Fragmentation adversely affects TCP throughput and network congestion. Setting this parameter to FALSE causes an MTU of 576 bytes to be used for all connections that are not to machines on the local subnet. The default is TRUE.

TcpMaxConnectRetransmissions

Uint32

Number of times TCP attempts to retransmit a Connect Request before terminating the connection. The initial retransmission time-out is 3 seconds. The retransmission time-out doubles for each attempt. Default: 3, Valid Range: 0–0xFFFFFFFF.

TcpMaxDataRetransmissions

Uint32

Number of times TCP re-transmits an individual data segment (non-connect segment) before terminating the connection. The retransmission time-out doubles with each successive retransmission on a connection. Default: 5, Valid Range: 0–0xFFFFFFFF.

TcpNumConnections

Uint32

Maximum number of connections that TCP can have open simultaneously. Default: 0xFFFFFE, Valid Range: 0–0xFFFFFE.

TcpUseRFC1122UrgentPointer

Boolean

If TRUE, TCP uses the RFC 1122 specification for urgent data. If FALSE (default), TCP uses the mode used by Berkeley Software Design (BSD) derived systems. The two mechanisms interpret the urgent pointer differently and are not interoperable. Windows 2000 and Windows NT 3.51 and later default to BSD mode.

TcpWindowSize

Uint16

Units: Bytes

Maximum TCP Receive Window size offered by the system. The Receive Window specifies the number of bytes a sender may transmit without receiving an acknowledgment. In general, larger receiving windows will improve performance over high delay and high bandwidth networks. For efficiency, the receiving window should be an even multiple of the TCP Maximum Segment Size (MSS). Default: Four times the maximum TCP data size or an even multiple of TCP data size rounded up to the nearest multiple of 8192. Ethernet networks default to 8760. Valid range: 0–5535.

All the properties in the previous table are read-only.

Table 30 describes the Win32_NetworkAdapterConfiguration methods that work with TCP settings.

Table 30   Win32_NetworkAdapterConfiguration TCP Methods

Method

Parameters

Description

SetKeepAliveInterval

KeepAliveInterval – int32

Value, in milliseconds, for the interval separating Keep Alive Retransmissions until a response is received.

Static method. Sets the interval separating Keep Alive Retransmissions until a response is received. After a response is received, the delay until the next Keep Alive Transmission is again controlled by the value of the KeepAliveTime property. The connection is terminated after the number of retransmissions specified by the TcpMaxDataRetransmissions property have gone unanswered.

SetKeepAliveTime

KeepAliveTime – uint32

Interval, in milliseconds, the TCP waits to check that an idle connection is still available.

Static method. Sets how often TCP attempts to verify that an idle connection is still available by sending a Keep Alive packet. If the remote system is still reachable and functioning, it will acknowledge the Keep Alive transmission. Keep Alive packets are not sent by default. This feature may be enabled in a connection by an application.

SetMTU

Windows Server 2003: This method is not supported. No replacement exists and the values do not correspond to the intended purpose of the method.

MTU – int32

Default Maximum Transmission Unit (MTU) for a network interface The range of this value spans the minimum packet size (68) to the MTU supported by the underlying network.

Static method. Sets the default Maximum Transmission Unit (MTU) for a network interface. The MTU is the maximum packet size (in bytes) that a transport will transmit over the underlying network. The size includes the transport header.

Note that an IP datagram can span multiple packets. Values larger than the default for the underlying network result in the transport using the network default MTU. Values smaller than 68 result in the transport using an MTU of 68.

SetPMTUBHDetect

PMTUBHDetectEnabled – Boolean

If TRUE, TCP attempts to discover black hole and route packets in different network paths.

Static method. Enables detection of black hole routers while doing Path MTU Discovery. A black hole router does not return the Internet Control Message Protocol (ICMP) Destination Unreachable messages when it needs to fragment an IP datagram with the Don't Fragment bit set. TCP depends on receiving these messages to perform Path MTU Discovery.

With this feature enabled, TCP will try to send segments without the Don't Fragment bit set if several retransmissions of a segment go unacknowledged. If the segment is acknowledged as a result, the maximum segment size (MSS) will be decreased and the Don't Fragment bit will be set in future packets on the connection. Enabling black hole detection increases the maximum number of retransmissions performed for a given segment.

SetPMTUDiscovery

PMTUDiscoveryEnabled – Boolean

If TRUE, TCP is enabled to attempt to discover the Maximum Transmission Unit (MTU) or largest packet size over the path to a remote host. The default is TRUE.

Static method. Enables Maximum Transmission Unit (MTU) discovery over the path to a remote host. By discovering the Path MTU and limiting TCP segments to this size, TCP can eliminate fragmentation at routers along the path that connect networks with different MTUs. Fragmentation adversely affects TCP throughput and network congestion. Setting this parameter to FALSE causes an MTU of 576 bytes to be used for all connections that are not to machines on the local subnet.

SetTcpMaxConnectRetransmissions

TcpMaxConnectRetransmissions – int32

Number of attempts TCP will retransmit a connect request before aborting. The valid range for values is 0–0xFFFFFFFF.

Static method. Sets the number of attempts TCP will retransmit a connect request before aborting. The initial retransmission time-out is 3 seconds, and doubles for each attempt.

SetTcpMaxDataRetransmissions

TcpMaxDataRetransmissions – int32

Number of times TCP retransmits an individual data segment before aborting the connection. Valid range: 0–0xFFFFFFFF.

Static method. Sets the number of times TCP retransmits an individual data segment before aborting the connection. The retransmission time-out doubles with each successive retransmission on a connection.

SetTcpNumConnections

TcpNumConnections – int32

Maximum number of connections that TCP may have open simultaneously. Valid range: 0–0xFFFFFE.

Static method. Sets the maximum number of connections that TCP may have open simultaneously.

SetTcpUseRFC1122UrgentPointer

TcpUseRFC1122UrgentPointer – Boolean

If TRUE, TCP uses the RFC 1122 specification. If FALSE, urgent data is sent in the mode used by BSD-derived systems.

Static method. Specifies whether TCP uses the RFC 1122 specification for urgent data, or the mode used by Berkeley Software Design (BSD) derived systems. The two mechanisms interpret the urgent pointer in the TCP header and the length of the urgent data differently. They are not interoperable. Windows 2000 and Windows NT 3.51 or later default to BSD mode.

SetTcpWindowSize

TcpWindowSize – int16

Maximum TCP receive window size (in bytes) offered by the system. Valid range (in bytes): 0–65535.

Static method. Sets the maximum TCP Receive Window size offered by the system. The receive window specifies the number of bytes a sender can transmit without receiving an acknowledgment. In general, larger receive windows improve performance over high delay and high bandwidth networks. For efficiency, the receive window should be an even multiple of the TCP Maximum Segment Size (MSS).

All the methods in the previous table return a positive integer:

  • 0 indicates successful completion.

  • 1 indicates successful completion with reboot required.

  • Numbers greater than 1 indicate that some problem was encountered and the method could not complete. The WMI SDK lists the meanings of return values for these methods.

Managing IP Packet Settings

Table 31 describes the Win32_NetworkAdapterConfiguration properties that work with Internet Protocol (IP) settings.

Table 31   Win32_NetworkAdapterConfiguration IP Properties

Property

Type

Description

DefaultTOS

Uint8

Default Type Of Service (TOS) value set in the header of outgoing IP packets. Request for Comments (RFC) 791 defines the values. Default: 0, Valid Range: 0–255.

DefaultTTL

Uint8

Default Time To Live (TTL) value set in the header of outgoing IP packets. The TTL specifies the number of routers an IP packet can pass through to reach its destination before being discarded. Each router decrements by one the TTL count of a packet as it passes through and discards the packets—if the TTL is 0 (zero). Default: 32, Valid Range: 1–255.

IPUseZeroBroadcast

Boolean

If TRUE, IP zeros-broadcasts are used (0.0.0.0), and the system uses ones-broadcasts (255.255.255.255). Computer systems generally use ones-broadcasts, but those derived from BSD implementations use zeros-broadcasts. Systems that do not use the same broadcasts cannot interoperate on the same network. The default is FALSE.

All the properties in the previous table are read-only.

Table 32 describes the Win32_NetworkAdapterConfiguration methods that work with IP settings.

Table 32   Win32_NetworkAdapterConfiguration IP Methods

Method

Parameters

Description

SetDefaultTOS

Obsolete. Applications should use the QoS API to manipulate TOS bits.

DefaultTOS – string

Parameter is Type of Service (TOS) value put in the header of outgoing IP packets. For a definition of the values, see RFC 791.

Static method. Sets the default Type of Service (TOS) value in the header of outgoing IP packets.

SetDefaultTTL

DefaultTTL – uint 8

Parameter is the Time to Live value set in the header of outgoing IP packets. Default: 32; Valid range: 1–255

Static method. Sets the default Time to Live (TTL) value in the header of outgoing IP packets. The TTL specifies the number of routers an IP packet may pass through to reach its destination before being discarded. Each router decrements the TTL count of a packet by one and discards the packets with a TTL of 0.

SetIPUseZeroBroadcast

IPUseZeroBroadcast – Boolean

If TRUE, IP zero broadcast is used. The default is FALSE.

Static method. Set IP zero broadcast usage. If the IPUseZeroBroadcast parameter is set to TRUE, then IP will use zero-broadcasts (0.0.0.0) instead of one-broadcasts (255.255.255.255). Most systems use one-broadcasts, but systems derived from BSD implementations use zero-broadcasts. Systems that use different broadcasts will not interoperate on the same network.

All the methods in the previous table return a positive integer:

  • 0 indicates successful completion.

  • 1 indicates successful completion with reboot required.

  • Numbers greater than 1 indicate that some problem was encountered and the method could not complete. The WMI SDK lists the meanings of return values for these methods.

Retrieving ARP, TCP, and IP Packet Settings

ARP, TCP, and IP packet settings are typically used primarily on routers. Note that these properties are often empty or null on computers not configured as routers.

Scripting Steps

Listing 49 retrieves and displays ARP, IP, and TCP packet settings.

  1. Create a variable and assign the name of a computer to it. For the local computer, simply specify "." as the computer name. To run this script remotely, specify the name of an accessible remote computer on your network on which you have administrative privileges. The name can be in the form of either a host name or an IP address.

  2. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  3. Use the ExecQuery method to query the Win32_NetworkAdapterConfiguration class, filtering the WQL query with “WHERE IPEnabled = True.”

    This returns a collection consisting of all the network adapter configurations on the computer for which IP is enabled.

  4. For each network adapter configuration in the collection, display the ARP, IP, and TCP properties, each under its own heading.

Listing 49   Arp-ip-tcp-settings.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


On Error Resume Next
 
strComputer = "."
 
Set objWMIService = GetObject("winmgmts:" & _
 "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Set colNicConfigs = objWMIService.ExecQuery("SELECT * FROM " & _
 "Win32_NetworkAdapterConfiguration WHERE IPEnabled = True")
 
WScript.Echo VbCrLf & "ARP, IP and TCP packet settings"
WScript.Echo VbCrLf & "Host Name: " & strComputer
 
For Each objNicConfig in colNicConfigs
  WScript.Echo VbCrLf & "  Network Adapter: " & objNicConfig.Index & _
   VbCrLf & "   " & objNicConfig.Description
  WScript.Echo VbCrLf & "   ARP Settings:"
  WScript.Echo "    ARP queries use source routing on Token Ring: " & _
   objNicConfig.ArpAlwaysSourceRoute
  WScript.Echo "    ARP uses SNAP encoding on Ethernet: " & _
   objNicConfig.ArpUseEtherSNAP
  WScript.Echo VbCrLf & "   IP packet settings:"
  WScript.Echo "    Default Type Of Service: " & objNicConfig.DefaultTOS
  WScript.Echo "    Default Time To Live: " & objNicConfig.DefaultTTL
  WScript.Echo "    IP uses zeros-broadcasts: " & _
   objNicConfig.IPUseZeroBroadcast
  WScript.Echo VbCrLf & "   TCP Settings:"
  WScript.Echo "    Keep Alive Interval: " & objNicConfig.KeepAliveInterval
  WScript.Echo "    Keep Alive Time: " & objNicConfig.KeepAliveTime
  WScript.Echo "    Maximum Transmission Unit: " & objNicConfig.MTU
  WScript.Echo "    Maximum Transmission Unit path discovery enabled: " & _
   objNicConfig.PMTUDiscoveryEnabled
  WScript.Echo "    Maximum number of connect request retransmissions: " & _
   objNicConfig.TcpMaxConnectRetransmissions
  WScript.Echo "    Maximum number of data segment retransmissions: " & _
   objNicConfig.TcpMaxDataRetransmissions
  WScript.Echo "    Maximum number of simultaneous open connections: " & _
   objNicConfig.TcpNumConnections
  WScript.Echo "    Use RFC 1122 specification for urgent data: " & _
   objNicConfig.TcpUseRFC1122UrgentPointer
  WScript.Echo "    Maximum TCP receive window size: " & _
   objNicConfig.TcpWindowSize
Next

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>arp-ip-tcp-settings.vbs

 

ARP, IP and TCP packet settings

 

Host Name: .

 

  Network Adapter: 1

   3Com 3C920 Integrated Fast Ethernet Controller (3C905C-TX Compatible) - Packe

t Scheduler Miniport

 

   ARP Settings:

    ARP queries use source routing on Token Ring:

    ARP uses SNAP encoding on Ethernet:

 

   IP packet settings:

    Default Type Of Service:

    Default Time To Live:

    IP uses zeros-broadcasts:

 

   TCP Settings:

    Keep Alive Interval:

    Keep Alive Time:

    Maximum Transmission Unit:

    Maximum Transmission Unit path discovery enabled:

    Maximum number of connect request retransmissions:

    Maximum number of data segment retransmissions:

    Maximum number of simultaneous open connections:

    Use RFC 1122 specification for urgent data:

    Maximum TCP receive window size:

Managing IPX

Internetwork Packet Exchange (IPX) is a protocol used by older Novell NetWare networks. Win32_NetworkAdapterConfiguration provides a few properties and methods for IPX configuration, which may be useful on networks that have both NetWare-based and Windows-based clients.

Table 33 describes the IPX properties for the Win32_NetworkAdapterConfiguration class.

Table 33   IPX Properties of the Win32_NetworkAdapterConfiguration Class

Property

Type

Description

IPXEnabled

Boolean

If TRUE, the IPX protocol is bound and enabled for this adapter.

IPXAddress

String

IPX address of the network adapter. The IPX address identifies a computer system on a network that uses the IPX protocol.

IPXFrameType

Uint32 array

Array of frame type identifiers. The values in this array correspond to the elements in IPXNetworkNumber.

O = Ethernet II

1 = Ethernet 802.3

2 = Ethernet 802.2

3 = Ethernet SNAP

255 = AUTO

IPXMediaType

Uint32

IPX media type identifier.

1 = Ethernet

2 = Token Ring

3 = FDDI

8 = ARCNET

IPXNetworkNumber

String array

Array of characters that uniquely identifies a frame/network adapter combination on the computer system. The NWLink IPX/SPX/NetBIOS Compatible Transport Protocol (NWLink) in Windows 2000 and Windows NT 4.0 and later use two distinctly different types of network numbers. This number is sometimes referred to as the external network number. It must be unique for each network segment. The order in this string list will correspond item-for-item with the elements in the IPXFrameType property.

IPXVirtualNetNumber

String

Unique identifier of the computer system on the network. It is represented in the form of an eight-character hexadecimal digit. Windows NT and Windows 2000 use the virtual network number (also known as an internal network number) for internal routing.

All the properties in the previous table are read-only.

Table 34 describes the IPX methods for the Win32_NetworkAdapterConfiguration class.

Table 34   IPX Methods for the Win32_NetworkAdapterConfiguration Class

Method

Parameters

Description

SetIPXFrameTypeNetworkPairs

IPXNetworkNumber – string array

Array of characters that uniquely identify an adapter on the computer system. The NWLink in Windows 2000 and Windows NT 3.51 or later uses two different types of network numbers. This number is sometimes referred to as the External Network Number. It must be unique for each network segment. The values in this string list must have a corresponding value in the IPXFrameType parameter identifying the packet frame type used for this network.

IPXFrameType - –int32 array

Integer array of frame type identifiers. The values in this array correspond to the elements in the IPXNetworkNumber parameter.

Static method. Sets IPX network number/frame pairs for this network adapter. Windows 2000 and Windows NT 3.51 or later use an IPX network number for routing purposes. It is assigned to each configured frame type/network adapter combination on your computer system. This number is sometimes referred to as the external network number. It must be unique for each network segment. If the frame type is set to AUTO, the network number should to zero.

SetIPXVirtualNetworkNumber

IPXNetworkNumber – string array

Array of characters that uniquely identify an adapter on the computer system. The NWLink in Windows 2000 and Windows NT 3.51 or later uses two different types of network numbers. This number is sometimes referred to as the External Network Number. It must be unique for each network segment. The values in this string list must have a corresponding value in the IPXFrameType parameter identifying the packet frame type used for this network.

IPXFrameType - –int32 array

Integer array of frame type identifiers. The values in this array correspond to the elements in the IPXNetworkNumber parameter.

Static method. Sets the IPX virtual network number on the target computer system. Windows 2000 and Windows NT 3.51 or later use an internal network number for internal routing. The internal network number is also known as a virtual network number, which uniquely identifies the computer system on the network.

All the methods in the previous table return a positive integer:

  • 0 indicates successful completion.

  • 1 indicates successful completion with reboot required.

  • Numbers greater than 1 indicate that some problem was encountered and the method could not complete. The WMI SDK lists the meanings of return values for these methods.

Scripting Steps

Listing 50 simply displays IPX-related properties; it does not configure any IPX settings. This script uses the VBScript Select Case statement to handle multiple possibilities for a value, in this case translating integers returned by the property into descriptive strings.

To carry out this task, the script must:

  1. Create a variable to specify the computer name.

  2. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  3. Use the ExecQuery method to query the Win32_NetworkAdapterConfiguration class.

    This returns a collection consisting of all the network adapter configurations on the computer.

  4. For each network adapter configuration in the collection, display the IPX properties.

  5. Use Select Case statements to translate the integer values returned by the IPXFrameType and IPXMediaType properties into descriptive strings.

Listing 50   Ipxsettings.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


On Error Resume Next
 
strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
 & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Set colNicConfigs = objWMIService.ExecQuery _
 ("SELECT * FROM Win32_NetworkAdapterConfiguration")
 
WScript.Echo VbCrLf & "IPX Settings"
 
For Each objNicConfig In colNicConfigs
  WScript.Echo VbCrLf & "  Network Adapter " & objNicConfig.Index
  WScript.Echo "    " & objNicConfig.Description
  WScript.Echo "    IPX Enabled: " & objNicConfig.IPXEnabled
  If objNicConfig.IPXEnabled Then
    WScript.Echo "    IPX Address: " & objNicConfig.IPXAddress
    WScript.Echo "    IPX Network Number(s):"
    If Not IsNull(objNicConfig.IPXNetworkNumber) Then
      For Each strIPXNetworkNumber In objNicConfig.IPXNetworkNumber
        WScript.Echo "        " & strIPXNetworkNumber
      Next
    End If
    WScript.Echo "    IPX Virtual Network Number: " & _
     objNicConfig.IPXVirtualNetNumber
    WScript.Echo "    IPX Frame Type(s):"
    If Not IsNull(objNicConfig.IPXFrameType) Then
      For Each intIPXFrameType In objNicConfig.IPXFrameType
        Select Case intIPXFrameType
          Case 0 strIPXFrameType = "Ethernet II"
          Case 1 strIPXFrameType = "Ethernet 802.3"
          Case 2 strIPXFrameType = "Ethernet 802.2"
          Case 3 strIPXFrameType = "Ethernet SNAP"
          Case 255 strIPXFrameType = "AUTO"
          Case Else strIPXFrameType = "Frame type cannot be determined."
        End Select
        WScript.Echo "        " & strIPXFrameType
      Next
    End If
    intIPXMediaType = objNicConfig.IPXMediaType
    Select Case intIPXMediaType
      Case 1 strIPXMediaType = "Ethernet"
      Case 2 strIPXMediaType = "Token ring"
      Case 3 strIPXMediaType = "FDDI"
      Case 255 strIPXMediaType = "ARCNET"
      Case Else strIPXMediaType = "Media type cannot be determined."
    End Select
    WScript.Echo "    IPX Media Type: " & strIPXMediaType
  End If
Next

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>ipxsettings.vbs

 

IPX Settings

 

  Network Adapter 1

    3Com 3C920 Integrated Fast Ethernet Controller (3C905C-TX Compatible) - Pack

et Scheduler Miniport

    IPX Enabled: False

 

  Network Adapter 2

    RAS Async Adapter

    IPX Enabled: False

 

  Network Adapter 3

    Packet Scheduler Miniport

    IPX Enabled: False

 

  Network Adapter 4

    WAN Miniport (L2TP)

    IPX Enabled: False

 

  Network Adapter 5

    WAN Miniport (PPTP)

    IPX Enabled: False

 

  Network Adapter 6

    WAN Miniport (PPPOE)

    IPX Enabled: False

 

  Network Adapter 7

    Direct Parallel

    IPX Enabled: False

 

  Network Adapter 8

    WAN Miniport (IP)

    IPX Enabled: False

 

  Network Adapter 9

    Packet Scheduler Miniport

    IPX Enabled: False

Enumerating the Network Protocols on a Computer

If you need to determine which network protocols are installed on a specific host, the WMI class Win32_NetworkProtocol provides access to a variety of parameters for each protocol. For the purposes of this paper, however, you probably need to know only whether TCP/IP, NetBIOS, and possibly IPX are installed, even though the class also returns information about other protocols such as QoS RSVP. Almost all the other properties of this class return details that are not relevant to scripting network clients.

You can also find out whether TCP/IP or IPX is installed on each network adapter by checking, respectively, the IPEnabled or IPXEnabled properties of Win32_NetworkAdapterConfiguration. To obtain information about NetBIOS on specific network adapters, use the TcpipNetbiosOptions property of Win32_NetworkAdapterConfiguration.

Win32_NetworkProtocol has no methods. All its properties are read-only and apply to the computer system as a whole, rather than to each network adapter (as most Win32_NetworkAdapterConfiguration properties do).

The way in which Win32_NetworkProtocol packages settings varies for each protocol. TCP/IP is listed as two protocol drivers: MSAFD Tcpip [TCP/IP] for TCP; and MSAFD Tcpip [UDP/IP] for UDP. Two NetBIOS interfaces are listed per network adapter (identified by GUID), one is called SEQPACKET and the other is called DATAGRAM.

Scripting Steps

Listing 51 lists all the network protocols installed on a computer.

  1. Create a variable and assign the name of a computer to it. For the local computer, simply specify "." as the computer name. To run this script remotely, specify the name of an accessible remote computer on your network on which you have administrative privileges. The name can be in the form of either a host name or an IP address.

  2. Use a GetObject call to connect to the WMI namespace root\cimv2, and set the impersonation level to “impersonate.”

  3. Use the ExecQuery method to query the Win32_NetworkProtocol class.

    This returns a collection consisting of all the network protocols installed on the computer.

  4. For each installed network protocol in the collection, display the protocol name, description and status.

Listing 51   Netprotocols.vbs

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17


On Error Resume Next
 
strComputer = "."
 
Set objWMIService = GetObject("winmgmts:" _
 & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Set colNetProtocols = objWMIService.ExecQuery _
 ("SELECT * FROM Win32_NetworkProtocol")
 
WScript.Echo VbCrLf & "Host: " & strComputer & VbCrLf & _
 "  Network Protocols Installed"
 
For Each objNetProtocol In colNetProtocols
  WScript.Echo VbCrLf & "    Protocol Name: " & objNetProtocol.Name
  WScript.Echo "      Description: " & objNetProtocol.Description
  WScript.Echo "      Status: " & objNetProtocol.Status
Next

When you use Cscript.exe to run this script, output similar to the following is displayed in the command window:

C:\scripts>netprotocols.vbs

 

Host: .

  Network Protocols Installed

 

    Protocol Name: MSAFD Tcpip [TCP/IP]

      Description: TCP/IP Protocol Driver

      Status: OK

 

    Protocol Name: MSAFD Tcpip [UDP/IP]

      Description: TCP/IP Protocol Driver

      Status: OK

 

    Protocol Name: RSVP UDP Service Provider

      Description: QoS RSVP

      Status: Unknown

 

    Protocol Name: RSVP TCP Service Provider

      Description: QoS RSVP

      Status: Unknown

 

    Protocol Name: MSAFD NetBIOS [\Device\NetBT_Tcpip_{90505148-4B0A-495D-A68D-A

131E8EFF247}] SEQPACKET 0

      Description: NetBIOS Interface

      Status: OK

 

    Protocol Name: MSAFD NetBIOS [\Device\NetBT_Tcpip_{90505148-4B0A-495D-A68D-A

131E8EFF247}] DATAGRAM 0

      Description: NetBIOS Interface

      Status: OK

 

    Protocol Name: MSAFD NetBIOS [\Device\NetBT_Tcpip_{837F1F4E-3E51-4718-95B0-C

5E31D76BCD1}] SEQPACKET 1

      Description: NetBIOS Interface

      Status: OK

 

    Protocol Name: MSAFD NetBIOS [\Device\NetBT_Tcpip_{837F1F4E-3E51-4718-95B0-C

5E31D76BCD1}] DATAGRAM 1

      Description: NetBIOS Interface

      Status: OK

 

    Protocol Name: MSAFD NetBIOS [\Device\NetBT_Tcpip_{136E1638-D8FC-4182-8FE7-9

3CFEC053BC7}] SEQPACKET 2

      Description: NetBIOS Interface

      Status: OK

 

    Protocol Name: MSAFD NetBIOS [\Device\NetBT_Tcpip_{136E1638-D8FC-4182-8FE7-9

3CFEC053BC7}] DATAGRAM 2

      Description: NetBIOS Interface

      Status: OK

Tools for Scripting Other Network Protocols

The Windows operating system provides tools and registry keys to use for scripting IPSec and other network protocols on clients. Table 35 lists the command-line tools for scripting IPSec and other protocols.

Table 35   Command-Line Tools for IPSec and Other Protocols

Command-Line Tool

Where Available

Arp.exe

Windows operating systems1

Getmac.exe

Windows 2000 Resource Kit

Hostname.exe

Windows operating systems

Ipconfig.exe

Windows operating systems

Ipseccmd.exe

Windows operating systems

Listadapters.vbs

Windows 2000 Resource Kit

Netconnections.vbs

Windows 2000 Resource Kit

Netipconfig.pl

Windows 2000 Resource Kit

Netipfilteringconfig.pl

Windows 2000 Resource Kit

Netipxspxconfig.pl

Windows 2000 Resource Kit

Net.exe

Windows operating systems

Netset.exe

Windows 2000 Resource Kit

Netsh.exe

Windows operating systems

Netstat.exe

Windows operating systems

Networkprotocol.vbs

Windows 2000 Resource Kit

Ping.exe

Windows operating systems

Protocolbinding.vbs

Windows 2000 Resource Kit

Remote.exe

Windows Server 2003 Support Tools

Remote Command Service (Rcmd.exe and Rcmdsvc.exe)

Windows 2000 Resource Kit

Remote Console

Windows 2000 Resource Kit

Rsh.exe and Rshsvc.exe: TCP/IP Remote Shell Service

Windows 2000 Resource Kit

Subnet_op.vbs

Windows 2000 Resource Kit

Telnet.exe

Windows operating systems

Timezone.exe: Daylight Saving Time Update Utility

Windows 2000 Resource Kit

Tzedit.exe: Time Zone Editor

Windows 2000 Resource Kit–GUI tool

Wsremote.exe

Windows XP Support Tools

1 Windows 2000, Windows XP and Windows Server 2003. May also be present on other versions of Windows.

Table 36 lists the WSH objects to use for scripting other network protocols.

Table 36   WSH Objects for Other Network Protocols

WSH Object

WshController

WshNetwork

WshShell

Table 37 lists the WMI classes to use for scripting other network protocols.

Table 37   WMI Classes for Other Network Protocols

WMI Class

Win32_NetworkAdapterConfiguration

Win32_NetworkAdapter

Win32_NetworkAdapterSetting (association Win32_NetworkAdapter - Win32_NetworkAdapterConfiguration)

Win32_NetworkProtocol

Win32_OperatingSystem

Win32_ProtocolBinding (association class)

Table 38 lists the registry keys to use for scripting other network protocols.

caution.gif  Caution
Incorrectly editing the registry may severely damage your system. Before making changes to the registry, you should back up any valued data on the computer.

Table 38   Registry Subkeys Related to Other Network Protocols

Registry Subkeys

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\Interfaces
\{AdapterIdentifier}

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Netman