Working with Netsh in Windows XP Embedded

Susannah A. Raub
Microsoft Corporation

October 2003

Applies to:
    Microsoft® Windows® XP Embedded with Service Pack 1 (SP1)
    Microsoft Windows XP Embedded

Abstract

Networked devices often have particular networking requirements such as static Internet Protocol (IP) addresses, Dynamic Host Configuration Protocol (DHCP), or multiple network cards. This paper explains how to configure these devices by successfully running Netsh, a command line drive utility, in a Windows XP Embedded environment.

Contents

Introduction
Overview of Netsh
Necessary Components
Critical Dependencies
Conclusion
Additional Resources

Introduction

Networked devices often have particular networking requirements such as static IP addresses, DHCP, or multiple network cards. The command line driven Netsh utility, included in Microsoft® Windows® XP Professional and Windows XP Embedded, is the cleanest and simplest way to configure these devices.

However, building a runtime that includes the appropriate components without inflating the footprint significantly can be somewhat tricky. In many cases, such as configuring devices as in the preceding examples, not all Netsh functionality is necessary. In addition to including the correct components and dependencies, problems have arisen in the naming of the interfaces if the Explorer Shell is not present. Following is information to customize your build and successfully run Netsh in a Windows XP Embedded environment.

Overview of Netsh

Netsh runs directly from the Windows command prompt. Netsh interacts with components of the operating system through groups of commands, or a context. Netsh uses auxiliary dynamic link libraries (DLLs) to extend its built-in features. Many contexts exist within Netsh to configure IPs, remote access server (RAS), routing, bridges, and much more.

Netsh itself is merely a "network shell" utility, and does not have a "static" dependency on the "helper" DLLs that provide specific functionality for different areas of networking. This is not unlike the CMD (Windows Command Processor) component in Windows XP Embedded: optional CMD utilities such as Copy and the PING protocol are not required for the CMD prompt to operate correctly.

Including all of the "helper" DLLs supported by the Netsh component can increase image footprint considerably. Because of this, the Netsh component and "helper" DLLs do not contain "Static" dependencies to each other, and need to be included separately to obtain the support required for each configuration.

Necessary Components

In order to run the interface context, four components are necessary in addition to basic Transmission Control Protocol/Internet Protocol (TCP/IP) networking components. The required components are as follows:

• CMD – Windows Command Processor
• Network Command Shell
• Network Command Shell Interface Context
• IP Router Monitor Library

These components enable some, but not all of the contexts provided in Windows XP Professional. Additional components increase the commands and contexts available. These components are as follows:

• Home Networking Monitory Library
• Network Diagnostics
• Remote Access Monitory

For details, see Table 1.

These components need to be added to your SLX in Target Designer. The Netsh show helper command displays specifically which DLLs are necessary for each command.

As a result of including some but not all of these components, the warning:

"WARNING: Could not obtain host information from machine: [machine name]. Some commands may not be available."

may appear. Use the command ? from the Netsh command prompt to list available commands. Table 1 shows which commands are available when each of the listed components is included.

• ?
• ..
• abort
• add
• alias
• bye
• commit
• delete
• exec
• exit
• help
• offline
• online
• popd
• pushd
• quit
• routing
• set
• show
• unalias

Table 1. Commands Available with Each Component

Critical Dependencies

If you are not using the Explorer shell, you may find that the interfaces are unnamed by default. Explorer names them automatically, so this problem will not be encountered once explorer.exe has run.

As a workaround to explicitly running explorer.exe, you can manually call the function HrRenameConnection by typing:

rundll32 netshell.dll HrRenameConnection

at the command prompt. If you examine the interface at this point, it will be named "Local Area Connection," or an equivalent in your local language. You can view this by running:

netsh interface ip show address

It is not sufficient to run the command Netsh interface ip set address "{GUID}" static; the interface must be named. Attempting to set the IP address before the interface has been named will result in the error:

"Invalid interface Local Area Connection specified."

If multiple NICs (network interface cards) are installed, HrRenameConnection will rename each adapter found – adding a number (GUID) to the name of each subsequent card.

At this point, the adapters can be configured using Netsh commands. For example, to set an IP address statically, run:

netsh interface ip set address "Interface name" static <ip address> <mask> <default gateway> <gateway metric>

As long as "Ok." appears in the command prompt, the command worked perfectly despite other errors.

Here is an example of setting the IP address statically to 192.168.1.10, with a network mask of 255.255.255.0, and a default gateway of 192.168.1.1. The gateway is followed by the interface metric, which is set to 1 when the router is local, as it is the number of hops to the router.

netsh interface ip set address "Local Area Connection" static 192.168.1.10 255.255.255.0 192.168.1.1 1

"WARNING: Could not obtain host information from machine: [machine name]. Some commands may not be available." Ok.

To enable DHCP, follow this example:

netsh interface ip set address "Local Area Connection" dhcp

"WARNING: Could not obtain host information from machine: [machine name]. Some commands may not be available." Ok.

There are two commands that can be used to configure multiple NICs. Here is an example of setting a static IP (like the previous example) and enabling DHCP:

Static IP

netsh interface ip set address "Local Area Connection" static 192.168.1.10 255.255.255.0 192.168.1.1 1

"WARNING: Could not obtain host information from machine: [machine name]. Some commands may not be available." Ok.

Enabling DHCP*

netsh interface ip set address "Local Area Connection 2" dhcp

"WARNING: Could not obtain host information from machine: [machine name]. Some commands may not be available." Ok.

* DCHP is enabled by default in Windows XP Professional and Windows XP Embedded. This example is provided for completeness, in the event that users that have set their configuration to a "Static" IP address and later require DHCP addressing.

In this example, the warning message can be ignored because the needed commands are all available. The "Ok." message signals that the IP addresses have been set correctly.

Conclusion

Netsh provides functionality to configure networking, and Target Designer allows you to build a runtime to include only the components you need for your configurations in a Windows XP Embedded environment. By tailoring Netsh to your networking needs, you can minimize the size of your runtime and still maintain necessary functionality.

It is recommended that users create "macro" components in Component Designer that will include all of the required Netsh components and dependencies. You can find more information about macro components in the 'Creating a Hardware Macro' section of this paper on MSDN. Netsh and its supporting component can be located under the Networking & Communications category in the Windows XP Embedded database. All the components listed in this article are included in the first release of Windows XP Embedded in addition to the Service Pack 1 release.

Additional Resources

For more information about Windows XP Embedded, visit the Windows XP Embedded Web site.

For online documentation and context-sensitive Help included with Windows XP Embedded, see Windows XP Embedded product documentation.

For information about Netsh and available commands, see Using Netsh in the XP Embedded product documentation.

© Microsoft Corporation. All rights reserved.