Managing IP Routes Through WMI

Viewing the Routing Table
To display the information in the IPv4 routing table, run WMIIP4Route.wsf with the PRINT parameter. The routing table is a collection of instances from the Win32_IP4RouteTable class. Because some properties of this class contain numbers that have a specific meaning, the script includes the DecodeIPRouteFunction.vbs helper file at the beginning of the WSH code. This file contains several functions to decode property values exposed by the Win32_IP4RouteTable class.

After the script's initialization phase, the code at callout A in Listing 1 retrieves all available instances from the Win32_IP4RouteTable class. Next, the script enumerates, in a loop, all available instances. The code at callout B determines whether an association exists between each retrieved instance of the Win32_IP4RouteTable class and an instance of the Win32_IP4Persisted-RouteTable class. If such an association exists, the examined IP route instance is a persistent route (i.e., an entry that's permanently inserted into the routing table and that persists even after a reboot). The Win32_ActiveRoute association class links the Win32_IP4RouteTable and Win32_IP4PersistedRouteTable classes, and the script uses the Win32_ActiveRoute class to determine whether routes are persistent (as well as to create persistent routes, as I show you later in the article). The code at callout C then displays the properties of each IP route instance. Web Figure 2 shows the resulting output.

Adding a Route
To add a new route, run WMIIP4Route.wsf with the ADD, MASK, METRIC, and IF parameters. The ADD parameter specifies the new network IP number, the MASK parameter specifies the IP mask to use, the METRIC parameter specifies the destination's IP cost, and the IF parameter specifies the network interface number. Immediately after the MASK parameter value and before the METRIC parameter, you must specify the gateway IP address route to the new network IP number. For example, the command

WMIIP4Route.wsf ADD 192.10.10.0
  MASK 255.255.255.0
  192.10.10.1 METRIC 2 IF 1

adds a route to 192.10.10.0 (using the IP mask 255.255.255.0 and the gateway route 192.10.10.1) with a metric cost of 2 through network interface 1.

To make the route persistent, you must use the /persistent+ switch, which is equivalent to the route.exe
-p parameter:

WMIIP4Route.wsf ADD 192.10.10.0
  MASK 255.255.255.0
  192.10.10.1 METRIC 2 IF 1
  /persistent+

To add a route remotely, add the /machine, /user, and /password switches:

WMIIP4Route.wsf ADD 192.10.10.0
  MASK 255.255.255.0
 192.10.10.1 METRIC 2 IF 1
  /persistent+
  /machine:MyRemoteSystem
    .lissware.net
  /user:Administrator
  /password:Password1
 

Listing 2 shows the code that WMIIP4Route.wsf uses to add an IP route. The Win32_IP4RouteTable class doesn't expose any method to add a route, so the code at callout A in Listing 2 spawns a Win32_IP4RouteTable instance--if an instance of the specified route doesn't already exist. To determine whether an instance exists, the script first tries to retrieve an existing instance of the IP route. If the route exists, the script updates the route with the new parameters. If the route doesn't exist, the script creates it. Note that the script doesn't expose a CHANGE parameter, as the route.exe command does. Rather, if the specified route already exists, the script's ADD command implements the same function as the CHANGE parameter.

Next, the code at callout B sets the route parameters. The code at callout C then uses the Put_ method of the SWbemObject object that represents the IP route instance to commit the route parameters.

If you specified the /persistent+ switch, the script next creates the WMI association to make the new route persistent. In such cases, the script creates two instances in addition to the Win32_IP4RouteTable instance. The first instance, which the code at callout D shows, is from the Win32_IP4PersistedRouteTable class. The creation of this instance follows a logic similar to the Win32_IP4RouteTable instance creation: The script first tries to retrieve the instance to determine whether it already exists, creates an instance if necessary, then sets the instance properties and saves the information in the Common Information Model (CIM) repository. The second instance, which the code at callout E shows, is from the Win32_ActiveRoute class. The script determines whether a Win32_ActiveRoute instance exists and, if not, creates the instance. To create or update the Win32_ActiveRoute instance, the script reuses the WMI path of the two previously created instances (i.e., the Win32_IP4RouteTable path instance and the Win32_IP4PersistedRouteTable path instance), then saves the information in the CIM repository.

Deleting a Route
To delete an existing route, run WMIIP4Route.wsf with the DELETE and MASK parameters, followed by the specified gateway route:

WMIIP4Route.wsf 
  DELETE 192.10.10.0
  MASK 255.255.255.0
  192.10.10.1

Listing 3 shows the code to delete a route from the routing table. This code also deletes the corresponding Win32_IP4RouteTable instance.

First, the code at callout A in Listing 3 retrieves the Win32_IP4RouteTable instance to be deleted. Before the script executes the deletion of the retrieved instance, the code at callout B determines whether an association exists between the instance and a Win32_IP4PersistedRouteTable instance. If the script finds an association, the code at callout C retrieves and deletes the associated Win32_IP4PersistedRouteTable instance. Deleting the associated instance is important because if the specified Win32_IP4RouteTable instance is recreated, the existence of a matching Win32_IP4PersistedRouteTable instance will automatically make the route persistent even if the /persistent+ switch isn't used during the recreation. After the script has retrieved all associated instances, the code at callout D deletes each instance. To delete a route remotely, add the /machine, /user, and /password switches, as you would when adding a route remotely.

On the Right Route
Computer security and management are hot topics, and the ability to monitor IP routes (for security reasons) and to manage routes remotely (as a great timesaver) are both important assets. If you deploy Windows 2003 or XP RAS or VPN servers, don't wait to leverage WMI's capability to improve your Windows management experience. Doing so can make life easier and give you another way to keep an eye on your network's security.