DO-009103-TC-6

ISOS UPnP IGD Feature and Interface Guide

DO-009103-PS (Issue 6, 6th Dec 2002)

ii ISOS UPnP IGD Feature and Interface Guide, DO-009103-PS (Issue 6, 6th Dec 2002)

CopyrightCopyright © 2002 GlobespanVirata Inc. All Rights Reserved.

This document and the software programs to which it relates are furnished under license and may only be used in accordance with the terms and conditions set forth in the license agreement. This document is provided for information only and is subject to change without notice. GlobespanVirata Inc assumes no responsibility or liability for any errors or inaccuracies that may appear in the document, and specifically disclaims any implied warranties of merchantability, fitness for a particular purpose, and non-infringement.

Except as permitted by such license, no part of this document may be copied, reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, recording or otherwise, or used as the basis for manufacture or sale of any items without the prior written consent of GlobespanVirata Inc.

GlobespanVirata® is a registered trademark of GlobespanVirata Inc.

All other names are for reference only and are the property of their respective owners.

ISOS UPnP IGD Feature and Interface Guide: DO-009103-PS

GlobespanVirata Company Proprietary.

TrademarksEmWeb® is a registered trademark of GlobespanVirata Inc.

ATMOS™ real-time operating system, Helium™ communications processor, Helium™ 200 communications processor, Helium™ 210 communications processor, Helium™ 500 communications processor, ISOS™ Integrated Software on Silicon, are trademarks of GlobespanVirata Inc.

The EmWeb Software Architecture is patented (U.S. Patent #5,973,696; other U.S. and international patents pending).

UPnPTM is a trademark of the Universal Plug and Play Forum.

Contacting GlobespanVirataFor more information on GlobespanVirata, contact the offices below or visit our web site:

http://www.globespanvirata.com

GlobespanVirata Headquarters100 Schulz DriveRed Bank, NJ 07701USAphone: +1-888-855-4562

GlobespanVirata UKUnit 230 Cambridge Science ParkMilton RoadCambridge CB4 0WBUnited Kingdomphone: +44 1223 707400

http://www.globespanvirata.com

Contents

1. About this Guide 11.1 Structure of this guide 21.2 Typographical conventions 31.3 Reading this guide 41.4 Conformance 41.5 Glossary 51.6 Useful Web Sites for UPnP 61.7 Related Documentation 6

2. Introduction 92.1 ISOS UPnP IGD 102.2 The ISOS Internet Gateway Device 112.3 Supported Device Types and Services 15

3. ISOS UPnP IGD Configuration 193.1 Introduction 203.2 Building the ISOS IGD 203.3 IGD Configuration 233.4 Device Driver Support 26

A: IGD Device and Service Templates 27B: UPnP Control Point Software 29

B.1 UPnP on Windows ME 30B.2 UPnP on Windows XP 30B.3 Internet Connection Firewall (Windows XP) 33

ISOS UPnP IGD Feature and Interface Guide Issue 6, 6th Dec 2002 iii

Contents

iv ISOS UPnP IGD Feature and Interface Guide Issue 6, 6th Dec 2002

List of Tables

Table 1: Useful web sites for UPnP 6Table 2: InternetGatewayDevice and Service Support 16Table 3: WANDevice and Service Support 16Table 4: WANConnectionDevice and Service Support 17Table 5: Port Slot Symbols 21

ISOS UPnP IGD Feature and Interface Guide Issue 6, 6th Dec 2002 1

List of Tables

2 ISOS UPnP IGD Feature and Interface Guide Issue 6, 6th Dec 2002

List of Figures

Figure 1 : ISOS IGD Communication 12Figure 2 : ISOS IGD (Combined router and broadband modem functions) 13Figure 3 : ISOS IGD (Separate router and broadband modem functions) 14Figure 4 : ISOS IGD Device and Service Hierarchy 15Figure 5 : Windows XP Networking Services window 31Figure 6 : Windows XP (SP1) Networking Services window 32Figure 7 : Windows XP Network Connections window 33

ISOS UPnP IGD Feature and Interface Guide Issue 6, 6th Dec 2002 1

List of Figures

2 ISOS UPnP IGD Feature and Interface Guide Issue 6, 6th Dec 2002

1. About this Guide

This chapter tells you about:• The scope of this guide and its intended

audience.• The typographical conventions used in this

guide.• How to read and provide feedback about this

guide.

The information contained in this guide must be read and fully understood before you attempt to use the product.

ISOS UPnP IGD Feature and Interface Guide DO-009103-PS (Issue 6, 6th Dec 2002) 1

Structure of this guide

1.1 Structure of this guide

1.1.1 ScopeThe ISOS UPnP Internet Gateway Device provides information about the GlobespanVirata implementation of the UPnP standard Internet Gateway Device (IGD).

The ISOS UPnP Internet Gateway Device describes how to configure the ISOS IGD for your environment. The manual provides information about Internet gateway devices and about the ISOS implementation of the UPnP IGD Device Control Protocol.

This manual is appropriate for ISOS 8.2 (SR2) and ISOS 9.0.

1.1.2 AudienceThis manual is intended for embedded systems application developers who are responsible for integrating the ISOS IGD into a local area network system. It is assumed that you are familiar with the concepts involved in UPnP, Internet gateway technologies, and ISOS configuration.

1.1.3 ContentGlobespanVirata distributes the ISOS IGD software as part of its ISOS distribution. The ISOS UPnP Internet Gateway Device is organized into the following chapters and appendices:• This chapter provides information about the manual organization,

document conventions, conformance information, useful Web sites, and a glossary.

• Introduction on page 9 provides an overview of the ISOS Internet Gateway Device.

• ISOS UPnP IGD Configuration on page 19 describes how to build and configure your ISOS IGD system.

• Appendix A, IGD Device and Service Templates on page 27 contains a listing of the UPnP device and service descriptions that apply to the ISOS IGD.

• Appendix B, UPnP Control Point Software on page 29 describes how to set up control point software on Windows ME and Windows XP systems.

2 ISOS UPnP IGD Feature and Interface Guide DO-009103-PS (Issue 6, 6th Dec 2002)

About this Guide

1.2 Typographical conventionsThroughout this guide, the following typographical conventions are used to denote important information.

1.2.1 Text conventionsThe following text conventions are used:• Text like this is used to introduce a new term, to indicate menu

options or to denote field and button names in GUI windows and dialogue boxes.

• Text like this is used to emphasize important points. For example:‘To keep your changes, you must save your work before quitting.’

• Text like this is used for text that you type as a command or entry to a field in a dialogue box. Variables to a command are shown in text like this.

• Text like this is used for text that you see on the screen in a terminal window. Variables to displayed text are shown in text like this.

• Text in square brackets is used to indicate keyboard keys. For example:‘To reboot your computer, press [Ctrl]+[Alt]+[Del].’

• Type versus Enter; Type means type the text as shown in the instruction. Enter means type the text as indicated and then press [Enter]; the Return key on the keyboard.

1.2.2 Notes, Warnings and CautionsThe following symbols are used:

Warning – Indicates a hazard which may endanger equipment or personnel if the safety instruction is not observed.

Caution – Indicates a hazard which may damage or destroy data if the instruction is not observed.

Note – Indicates general additional information about the operation of the equipment, including safety information.


Reading this guide

1.3 Reading this guide

1.3.1 Providing feedback on this guidePlease report support requests and questions to the Technical Advice Center (TAC) via the Support area on the GlobespanVirata Licensee Server at:

https://ls.globespanvirata.com/ls2

Once you have entered your user login and password you can access the Licensee Server. From the toolbar at the top of the page, click on Support.The GlobespanVirata Licensee Support page is displayed.

When submitting feedback, please give the full title, part number and version number of the guide.

1.3.2 Reading this guideAlthough this guide can be printed for easy reference, it has been prepared for viewing online through a web browser, (such as Internet Explorer™ or Netscape Navigator™) or Adobe Acrobat™.

Links to other sections of this guide or to other guides are marked in blue (although the links are black when printed on a standard laser printer). Click on the link to view the associated section or document.

1.4 ConformanceThe ISOS IGD conforms to the following standards:• urn:schemas-upnp-org:device:InternetGatewayDevice:1

(See http://www.upnp.org/)• The Universal Plug and Play Device Architecture (Version 1.0, 08

Jun 2000 )• HTTP/1.1 protocol (RFC 2616)• HTTP/1.0 protocol (RFC 1945) • Extensible Markup Language (XML) 1.0 (February, 1998)


About this Guide

1.5 GlossaryThe following list provides the definitions for terms and acronyms used in this manual.

control point A network device that supports UPnP network communication; control points obtain information about other devices (UPnP controlled devices) and use that information to direct the operations of these devices.

controlled device A network device that supports UPnP network communication and provides services and informa-tion about the state of the device to control points.

HTML Hypertext Markup Language - the language used to create documents for the World Wide Web.

HTTP Hypertext Transfer Protocol; one of the communi-cation protocols used on the World Wide Web, implemented in the EmWeb Server.

IGD The ISOS Internet Gateway Device; the ISOS implementation of the UPnP standard for an Inter-net gateway device.

LAN Local Area Network.

NAT Network Address Translation.

TCP/IP Transmission Control Protocol / Internet Protocol - the set of communication protocols used to connect computers on the Internet.

UPnP Universal Plug and Play - a device architecture for network communication.

URL Uniform Resource Locator - the network address of documents and other resources on the World Wide Web.


Useful Web Sites for UPnP

WAN Wide Area Network.

XML Extensible Markup Language; XML is a meta-lan-guage, or, a language for defining another lan-guage; XML is used to define markup tags for the Web.

1.6 Useful Web Sites for UPnP

1.7 Related DocumentationThis document relates to BUN version 3.0. However, it must be used in conjunction with the ISOS CLI Reference Manual and the ISOS User Guide appropriate to the environment in which you are working.

The most recent versions of the CLI Reference Manual are:• DO-009430-PS: ISOS 8.2 (SR2) CLI Reference Manual.• DO-009787-PS: ISOS 9.0 CLI Reference Manual.

Web Site Descriptionhttp://www.globespanvirata.com The GlobespanVirata Web site.

http://www.w3c.org

The World Wide Web consortium (information about HTTP, HTML, and other standards concerning the World Wide Web).

http://www.upnp.org The Universal Plug and Play Forum.

http://www.upnp.org/download/UPnPDA10_20000613

UPnP Device Architecture specification.

http://www.microsoft.com/hwdev/tech/nonpc/UPnP/default.asp

Microsoft UPnP device kit.

http://www.w3c.org/TR/2000/REC-xml-20001006

XML specification.

http://www.w3c.org/TR/1999/REC-xml-names-19990114/

XML Namespace specification.

http://www.isi.edu/in-notes/iana/assignments/media-types/

Site maintained by Internet Assigned Number Authority (IANA) at the Information Sciences Institute (ISI) of the University of Southern California (USC); contains the MIME media types registry

Table 1: Useful web sites for UPnP


About this Guide

while the most recent versions of the User Guide are:• DO-009467-PS: ISOS 8.2 (SR2) User Guide.• DO-400178-PS: ISOS 9.0 User Guide.

The other documents referred to in this manual are:• DO-009760-AN: UIC Certification of the UPnP IGD in ISOS.• DO-008620-LS: Web Content Compiler Enhanced License.


Related Documentation


2. Introduction

This chapter provides an introduction to the IGD, including an overview of the ISOS Internet Gateway Device and a listing of the supported UPnP device types and services.


ISOS UPnP IGD

2.1 ISOS UPnP IGDAn Internet Gateway Device (IGD) is a Universal Plug and Play (UPnP) device that supports network communication between devices on a Local Area Network and devices on the Internet. The GlobespanVirata IGD operates as an interface between a Local Area Network (LAN) and a Wide Area Network (WAN). GlobespanVirata’s UPnP IGD is an implementation of the UPnP standard for an Internet gateway device for Network Address Translation (NAT) traversal. The IGD is part of the Integrated Software on Silicon (ISOS) environment.

The GlobespanVirata IGD has been certified by the UPnP Implementors Corporation (UIC). The UIC is a non-profit corporation that administers the UPnP certification process. (For more information, see the Universal Plug and Play Forum Web site, http://www.upnp.org.).

As a GlobespanVirata licensee you can re-use the GlobespanVirata certified device - called ISOS UPnP IGD - and make some small modifications to customize the device. The custom device can then be submitted to the UIC for certification without the need for you to pay the registration fee as the device is functionally still an ISOS UPnP IGD. (For more information about how to re-use the GlobespanVirata UIC Certification of the UPnP IGD in ISOS, refer to UIC Certification of the UPnP IGD in ISOS, DO-009760-PS.)

To use the ISOS IGD, you integrate the IGD into your ISOS system and you configure the IGD device. (If you are using the ISOS system file for an Ethernet gateway or Home Router configuration, integration has already been encoded in the system file, and you only need to configure the IGD. For information about building and configuring the IGD, see ISOS UPnP IGD Configuration on page 19.)


Introduction

2.2 The ISOS Internet Gateway DeviceThe ISOS IGD is an implementation of version 1 of the UPnP Internet Gateway Device, which has device type:

urn:schemas-upnp-org:device:InternetGatewayDevice:1

This device description and its supporting device and service descriptions define the root device, contained devices, and services that combine to create a UPnP Internet Gateway Device. The ISOS IGD is a complete implementation of the subset of capabilities listed in Supported Device Types and Services on page 15. (To obtain the Internet Gateway Device description and its supporting device and service descriptions, see the UPnP Forum Web site http://www.upnp.org/).

To use the ISOS IGD:1 Integrate the IGD into your ISOS system. (If you are using the

system file supplied by GlobespanVirata, you can skip this step.)2 Configure your ISOS system for the requirements of your network

interface.

(These steps are described in ISOS UPnP IGD Configuration on page 19.)

Once you have accomplished these tasks, the ISOS IGD can operate as a UPnP controlled device application, and UPnP control points on your local network can communicate with the gateway device. The ISOS IGD uses GlobespanVirata’s EmWeb® UPnP technology to implement the controlled device that manages the Internet gateway. As a UPnP controlled device, the IGD supports the protocols that are required to


The ISOS Internet Gateway Device

communicate with local devices. Figure 1 is a general representation of the communication between a device on the local area network, the ISOS IGD, and the Internet.

Figure 1 ISOS IGD Communication1 A device on the local area network acts as a UPnP control point,

using the UPnP protocol to communicate with the ISOS IGD. The LAN device uses the IGD to manage the network interface, enabling or disabling incoming traffic (messages originating from the Internet). To accomplish this, the LAN device performs the appropriate set of UPnP operations:• The LAN device performs a UPnP discovery search operation

to find the IGD. (The LAN device can also receive UPnP discovery advertisements from the IGD.)

• Having obtained a discovery response (or advertisement) from the IGD, the LAN device retrieves the device description to obtain information about the set of devices and services in the IGD.

• Based on the IGD device and service descriptions, the LAN device uses the action "AddPortMapping" to open an external port to receive incoming messages from the Internet. (For a complete list of the ISOS IGD devices, services, actions, and state variables, see Table 2, Table 3 and Table 4 beginning on page 16.)

Incoming msgs

Outgoing msgs

Responses

UPnP msgs

UPnP responses1

2

3

ISOS IGD

UPnP Control Point

LAN device

ISP

Router

Incoming msgs

Outgoing msgs

Responses

Gateway


Introduction

2 When incoming messages are enabled, the gateway device operates as a router, accepting the messages and transmitting them to the LAN.

3 For normal traffic the gateway device operates as a router, handling outgoing messages and responses - for example, HTTP communication with Web servers on the Internet.

The ISOS IGD uses the router, NAT, firewall, and broadband modem capabilities of an ISOS gateway device to manage Internet access to local area network devices. The router and broadband capabilities can be configured as separate physical boxes, or they can be combined in a single box. Figure 2 shows a representation of an ISOS gateway device that contains combined router and broadband modem capabilities.

Figure 2 ISOS IGD (Combined router and broadband modem functions)

In the configuration shown in Figure 2, the gateway device has an Ethernet port for local area network access and a DSL port for Internet access. The ISOS IGD uses GlobespanVirata’s Network Address Translation (NAT) technologies to support the gateway capability:• The NAT software provides a set of internal, private addresses for

your local network, and presents a different set of external, public addresses for the Internet (or wide area network). Once a local device has established a connection with an external network, the ISOS NAT software automatically handles the address translation for incoming and outgoing messages.

• The Firewall manages access between the networks.

Internet Service Provider

Local Area Network

ISOS IGD

Ethernet

local device

DSL

Internal IP address

External IP address

local device

[NAT]

[Router][Broadband modem]

Gateway Device

[Firewall]


The ISOS Internet Gateway Device

• The ISOS IGD uses NAT traversal to define the port mapping for incoming network communication.

Figure 3 shows a representation of an ISOS gateway device that is comprised of separate router and broadband modem capabilities. The router device contains two Ethernet ports; the broadband device contains an Ethernet port and a DSL port. In this case, the ISOS IGD uses the NAT, router, and firewall functions of the router device (this device presents the internal and external IP addresses); the broadband modem device is a bridge to the Internet, providing Internet access to the router device (and the local area network).

Figure 3 ISOS IGD (Separate router and broadband modem functions)

Internet Service Provider

Local Area Network

ISOS IGDEthernet

local device

DSL

Internal IP address

External IP address

local device

[Router, Firewall]

[Broadband modem]

Ethernet

[NAT]

Gateway Device

[Bridge]


Introduction

2.3 Supported Device Types and ServicesAt run-time, the ISOS IGD builds its UPnP device hierarchy based on your ISOS system configuration (see IGD Configuration on page 23 for information about requirements for IGD configuration). The ISOS IGD implementation supports the following device hierarchy:• At least one WANDevice (representing the physical WAN

interface).• At least one WanConnectionDevice (defines variables and actions

common across all instances of WANIPConnections or WANPPPConnections in a WANDevice).

• One WAN*LinkConfig service (supports configuration parameters associated with a WAN link on a Digital Subscriber Link (DSL) modem, or an Ethernet-attached external modem (cable or DSL)).

• At least one WAN*Connection service (IP or PPP connections originating through the gateway).

Figure 4 is a representation of the ISOS IGD device and service hierarchy.

Figure 4 ISOS IGD Device and Service Hierarchy

WANDevice

WANConnectionDevice

WANDSLLinkConfig or WANEthernetLinkConfig Service

WANIPConnection or WANPPPConnection Service

InternetGatewayDevice

Layer3 Forwarding Service

WANCommonInterfaceConfig Service


Supported Device Types and Services

The tables below list the devices, services, actions, and state variables supported by the ISOS IGD. (See the appropriate UPnP device and service templates for information about these elements; for a list of the templates, see IGD Device and Service Templates on page 27.)

Device Type: InternetGatewayDeviceServices Actions State Variables

Layer3Forwarding SetDefaultConnectionServiceGetDefaultConnectionService DefaultConnectionService

Table 2: InternetGatewayDevice and Service Support

Device Type: WANDeviceServices Actions State Variables

WANCommonInterfaceConfig GetCommonLinkProperties

WANAccessTypeLayer1UpstreamMaxBitRateLayer1DownstreamMaxBitRatePhysicalLinkStatus

Table 3: WANDevice and Service Support


Introduction

Device Type: WANConnectionDeviceServices Actions State Variables

WANDSLLinkConfigSetDSLLinkTypeGetDSLLinkInfoGetAutoConfig

LinkTypeLinkStatusAutoConfig

WANEthernetLinkConfig GetEthernetLinkStatus EthernetLinkstatus

WANIPConnection

SetConnectionTypeGetConnectionTypeInfoRequestConnectionForceTerminationGetStatusInfoGetNATRSIPStatusGetGenericPortMappingEntryAddPortMappingDeletePortMappingGetExternalIPAddress

ConnectionTypePossibleConnectionTypesConnectionStatusUptimeLastConnectionErrorRSIPAvailableNATEnabledExternalIPAddressPortMappingNumberOfEntriesPortMappingEnabledPortMappingLeaseDurationRemoteHostExternalPortInternalPortPortMappingProtocolInternalClientPortMappingDescription

WANPPPConnection

SetConnectionTypeGetConnectionTypeInfoRequestConnectionForceTerminationGetStatusInfoGetLinkLayerMaxBitRatesGetNATRSIPStatusGetGenericPortMappingEntryGetSpecificPortMappingEntryAddPortMappingDeletePortMappingGetExternalIPAddress

ConnectionTypePossibleConnectionTypesConnectionStatusUptimeLastConnectionErrorRSIPAvailableNATEnabledExternalIPAddressPortMappingNumberOfEntriesPortMappingEnabledPortMappingLeaseDurationRemoteHostExternalPortInternalPortPortMappingProtocolInternalClientPortMappingDescription

Table 4: WANConnectionDevice and Service Support


Supported Device Types and Services


3. ISOS UPnP IGD Configuration

This chapter provides information about building and configuring the IGD.


Introduction

3.1 IntroductionGlobespanVirata distributes the ISOS IGD software as part of its ISOS distribution. To use the ISOS IGD, you build your ISOS system and then configure the IGD device. Once you have accomplished these tasks, your ISOS IGD can operate as a UPnP controlled device, and UPnP control points on your local network can communicate with the gateway device. The following sections provide directions for building and configuring the IGD. There is also information about support that the IGD requires if you provide your own device drivers.• Building the ISOS IGD (See Building the ISOS IGD on page 20).• Configuring the ISOS IGD (See IGD Configuration on page 23).• Device driver support (See Device Driver Support on page 26).

3.2 Building the ISOS IGDTo build an ISOS IGD application, you provide IGD device information for compile-time configuration. The IGD must also be enabled; GlobespanVirata supplies system files in the atmos/system directory which contains definitions to enable the IGD.

The ISOS IGD requires ISOS 8.2 (SR 2) (or later). The following sections describe how to:• Define the IGD port slots (IGD Port Slots on page 20).• Enable the IGD for ISOS (Integrating the IGD into your system on

page 22; Home Router and Ethernet Gateway configurations already enable the IGD by default).

Once you have performed these steps, you can build and run your ISOS system, after which you can perform run-time IGD configuration (see IGD Configuration on page 23).

3.2.1 IGD Port SlotsThe IGD defines a set of symbols that define the maximum number of ports and connections that your system requires. You use these symbols to specify, in advance, the maximum number of slots for ports and connections within the IGD. The values must be large enough to satisfy the requirements of your system. However, note that the ISOS IGD pre-allocates memory based on these values; for this reason, do not set limits that are larger than needed, since that will have an adverse effect on the UPnP control points and the network.


ISOS UPnP IGD Configuration

The IGD source code provides a set of default values that may be suitable for your system. The slot definitions are located in the file atmos/source/webserver/igd_src/database.h. (For each symbol, the value should be at least 1.) Table 5 shows the slot symbols.

Note the following:• If you specify a value that is too small for one of the port slot

symbols, it is possible that some interfaces will be invisible to the IGD.

• The IGD only understands "internal" (LAN) and "external" (WAN) ISOS Security interfaces. IP interfaces that do not have an ISOS security interface classification, or that are classified as a "DMZ" ISOS security interface, will not be visible via the IGD.

• In earlier versions of ISOS (ISOS 8.2 and ISOS 8.2 SR1), if the configured WAN interface was not running PPP (oE or oA) over DSL the port slot symbols had to be edited to make the configured WAN device be the first one in the UPnP device description document (DDD). For example, for an Ethernet routed configuration, IGD_LIMIT_WAN_DEVICE_DSL and IGD_LIMIT_WAN_PPP_CONNECTION_SERVICE would both be set to 0. It is no longer necessary to make such changes: the UPnP DDD will now be generated dynamically from the configured WAN interface and, if the configuration is changed, will be re-generated as necessary.

Port Slot Type Default ValueExternal DSL ports (maximum) #define IGD_LIMIT_WAN_DEVICE_DSL 1

External Ethernet ports (maximum) #define IGD_LIMIT_WAN_DEVICE_ETHERNET 1

PPP connections per port (maximum)

#define IGD_LIMIT_WAN_CONNECTION_DEVICE 2

IP sessions per channel (maximum)

#define IGD_LIMIT_WAN_IP_CONNECTION_SERVICE 1

IP sessions per PPP connection (maximum)

#define IGD_LIMIT_WAN_PPP_CONNECTION_SERVICE 1

Table 5: Port Slot Symbols


Building the ISOS IGD

3.2.2 Integrating the IGD into your systemTo build a system that includes the ISOS Internet Gateway Device capability:1 Add the following lines to the appropriate system file:

set with_upnpset with_igd

Note – The ISOS distribution kit provides many system files in the directory atmos/system, which contains these lines. (Thus, you must remove or comment out these lines from the system file you are using if you wish to build an ISOS system without the IGD.).

2 Use the GlobespanVirata Tools package (V8.41 or later) to set up the build environment. (See the Tools documentation that is appropriate for your operating system environment.)

3 Set up your Web Content Compiler license. (See the ISOS document Web Content Compiler Enhanced License (DO-008620-LS).)

4 To set the vendor-specific information in the IGD device description, edit the following file:atmos/source/webserver/igd_content/identification.xml

This file contains vendor-specific tags for information about the device manufacturer and model.

Note – Do not modify the line that begins with "<UDN>".

5 To build the ISOS system, set your working directory to the atmos/ root directory and run mkproduct with the following commands:cd atmos/mkproduct <product-type> <hardware-type>where <product-type> identifies the system file for the appropriate product configuration and <hardware-type> is the appropriate hardware file. For example:mkproduct eth-gateway bd6000



3.3 IGD ConfigurationAfter you have built your ISOS system (with the ISOS IGD enabled), you perform ISOS system configuration (the IGD software derives information from your ISOS system configuration). You also provide additional UPnP device configuration information. The following sections describe: • Transport and router configuration (Transport and Router

Configuration on page 23).• Security configuration (Security Configuration on page 24)• UPnP configuration (UPnP Configuration on page 25).

3.3.1 Transport and Router ConfigurationTo support data transfer through the IGD, you need to configure the device in a routed configuration.

For examples of typical routed configurations supported by the IGD, refer to the Configuration chapters in the ISOS User Guide appropriate for the ISOS release you are using.

If you are using Windows ME or Windows XP, the ISOS IGD will work with many of the configuration examples used in the ISOS User Guide.

If you are using Windows XP (SP1) then you need to configure the IGD with a static IP address and also setup the device as the DHCP server for the rest of the computers on the LAN.

A PC running Windows XP (SP1) will only recognise the IGD if the LAN IP address of the IGD is the same as the PC’s default Gateway IP address. In addition, the DHCP server, it must be configured with hostisdefaultgateway enabled. For example:

dhcpserver set subnet mysubnet hostisdefaultgateway enabled

There are also a few issues that you need to be aware of when using Windows XP (Service Pck 1):• There is a possible race condition at Windows boot time in that

DHCP may not supply the gateway address before the IGD device description document is loaded. If this happens, XP will decide that the IGD is not the default gateway and will not create an icon in Network Connections.


IGD Configuration

• It has also been observed that Windows XP Service Pack 1 occasionally gets into a state where it ignores "byebye" and "alive" messages from the IGD, with the result that the icon in "Network Connections" does not disappear and reappear when the operating mode is changed. (This problem may exist with the original version of Windows XP.)

To resolve either of these problems, disconnect the network cable from the PC for about 10 seconds (until any IGD icons have disappeared from"Network Connections") and then re-connect it. Alternatively, if access to the network cable is inconvenient, issue the "ipconfig /release" and "ipconfig /renew" commands at a Windows command prompt. If the problem persists, it may be necessary to reboot the PC

For descriptions of the configuration commands that can be used to setup transports and a routed configuration, see the ISOS CLI Reference Manual appropriate for the ISOS release you are using. (For more information, refer to Related Documentation on page 6.)

3.3.2 Security ConfigurationTo support the mapping between the internal and external IP interfaces, you need to configure security on the Gateway device.

The ISOS Security package allows you to define the extent of access allowed through the Gateway device. You can limit access to only those interfaces that you explicitly configure, or you can use the system-defined policies that provide access for standard protocols.

As a minimum, NAT needs to be enabled between an internal security interface and an external security interface for IGD NAT traversal to work correctly.

You will need to create a Firewall (Internal-External) security policy. This type of policy supports data transfer between the external and internal interface.



This security policy will also support IGD port mapping for incoming messages. When a UPnP control point on the local network invokes the AddPortMapping action for the WANIPConnection service, the ISOS IGD automatically uses the Firewall (Internal-External) policy to setup the port filters when it makes the connection.

Note – Note that NAT traversal and Firewall traversal are different. A strong Firewall configuration, above and beyond NAT being enabled, could cause networking applications to fail, even though they may work when only NAT is enabled.

For examples of setting up Security under ISOS, refer to the Security chapter in the ISOS User Guide appropriate for the ISOS release you are using. (For more information, refer to Related Documentation on page 6.)

3.3.3 UPnP ConfigurationUse the following Command Line Interface (CLI) commands to perform UPnP configuration for the ISOS IGD:

webserver show infowebserver set interfacewebserver set upnpport

You enter these commands interactively. To activate the configuration, use the system config save command to save the webserver commands, then reboot your system. (For more information about the system config save command, see the ISOS CLI Reference Manual, appropriate for the ISOS release you are using..) The following sections describe how to use the webserver commands.

UPnP Configuration Information (webserver show info)

To display information about the UPnP configuration (as well as other Web Server information), use the webserver show info command:

webserver show info

IGD IP Interface (webserver set interface)

The IGD requires the name of the IP interface that will be used for UPnP communication with devices on the local area network. To set the IP interface name, use the webserver set interface CLI command:

webserver set interface ip-name


Device Driver Support

For the "ip-name" value, substitute the name of the IP interface that you intend to use to receive UPnP messages for IGD control. This is usually the internal interface on the gateway. (The IGD itself can use any internal interface on the gateway, but UPnP control points can only use the specified interface to control the IGD.)

UPnP Port Number (webserver set upnpport)

You must set the port number to be used for UPnP communication. Use the webserver set upnpport CLI command:

webserver set upnpport port-number

The recommended "port-number" value is 2800. Note that this is different from the HTTP port (port 80). The IGD accepts UPnP messages (for advertisement, event registration, and performing actions) only on the UPnP port.

Do not use a reserved port number (port < 1024) because this will prevent inter-operation with Windows XP if the Microsoft patch Q315000 (unchecked UPnP buffer) or Windows XP Service Pack 1 has been installed.

3.4 Device Driver SupportIf you supply your own device drivers, you must implement support for the following BUN attributes:• Connected

• Either LinkSpeed or both RxBitRate and TxBitRateThe LinkSpeed attribute is measured in 100bps. Therefore:bit rate = 100 * LinkSpeed. RxBitRate and TxBitRate are measured in bps.


A:IGD Device and Service Templates

This appendix defines the device and service templates used by the ISOS IGD.


The ISOS IGD implementation is based on the following UPnP device and service descriptions:• InternetGatewayDevice:1 Device Template Version 1.01 for

Universal Plug and Play Version 1.0 • WANDevice:1 Device Template Version 1.01 for Universal Plug

and Play Version 1.0 • WANConnectionDevice:1 Device Template Version 1.01 for

Universal Plug and Play Version 1.0 • WANIPConnection:1 Service Template Version 1.01 for Universal

Plug and Play Version 1.0 • WANPPPConnection:1 Service Template Version 1.01 for

Universal Plug and Play Version 1.0 • WANDSLLinkConfig:1 Service Template Version 1.01 for

Universal Plug and Play Version 1.0 • WANEthernetLinkConfig:1 Service Template Version 1.01 for

Universal Plug and Play Version 1.0 • Layer3Forwarding:1 Service Template Version 1.01 for Universal

Plug and Play Version 1.0

For access to these templates, see the UPnP forum Web site (http://www.upnp.org/).


B:UPnP Control Point Software

This appendix describes how to install the Windows Control Point software on Windows XP and Windows ME.


UPnP on Windows ME

In a test environment, you may be using UPnP control point software on a Windows ME or Windows XP system to communicate with the IGD. You can use the control point software to detect the presence of the IGD controlled device on the network; once the control point displays the IGD icon, you can click on the icon to display the presentation Web pages supplied with the ISOS distribution kit. (You can change the Web content on these pages, according to your ISOS license.)

The following sections describe the procedure you use to install the control point software.• UPnP on Windows ME (UPnP on Windows ME on page 30)• UPnP on Windows XP (UPnP on Windows XP on page 30)

B.1 UPnP on Windows METo install the control point software on Windows ME: 1 In the Control Panel, select "Add/Remove Programs". 2 In the "Add/Remove Programs Properties" dialog box, select the

"Windows Setup" tab. In the "Components" list, double click on the "Communications" entry.

3 In the "Communications" dialog box, scroll down the "Components" list to display the UPnP entry. Select the entry, click "OK".

4 Click "OK" to finish the "Add/Remove Programs" dialog. 5 Reboot your system.

Once you have installed the UPnP software and you have rebooted (and your network includes the IGD system), you should be able to see the IGD controlled device on your network.

B.2 UPnP on Windows XPTo install the control point software on Windows XP: 1 In the Control Panel, select "Add/Remove Programs". 2 In the "Add or Remove Programs" dialog box, click the "Add /

Remove Windows Components" button.


3 In the "Windows Component Wizard" dialog box, scroll down the list to display the "Networking Services" entry. Highlight (select) the entry, and click on the "Details" button.The “Networking Services” window is displayed. The subcomponents shown in the Networking Services window will be different depending on if you are using Windows XP or Windows XP (SP1).If you are using Windows XP, the Networking Services window will display the following list of sub-components:

Figure 5 Windows XP Networking Services window


UPnP on Windows XP

If you are using Windows XP (SP 1), the Networking Services window will display the following list of sub-components:

Figure 6 Windows XP (SP1) Networking Services window4 Select the following entries from the “Networking Services”

window and then click "OK":If you are using Windows XP, select:• "Universal Plug and Play".If you are using Windows XP SP1, select:• "Internet Gateway Device discovery and Control Client".• "Universal Plug and Play".

5 Reboot your system.

Once you have installed the UPnP software and you have rebooted (and your network includes the IGD system), you should be able to see the IGD controlled device on your network.


For example, from the Network Connections window you should see the Internet Gateway Device:

Figure 7 Windows XP Network Connections window

Windows XP includes Firewall software that may prevent you from using the IGD (in particular, displaying the presentation Web page that is supplied with the ISOS software); see the following section for directions on turning off the Windows XP Firewall capability.

B.3 Internet Connection Firewall (Windows XP)You cannot use the Windows XP Internet Connection Firewall support on a system that you intend to use as a UPnP control point. If this feature is enabled, although the control point system may display controlled devices in the list of network devices, the control point system cannot participate in UPnP communication. (This restriction applies to controlled devices running on Windows XP systems as well.) To turn off the firewall capability:1 In the Control Panel, select "Network and Internet Connections".2 In the "Network and Internet Connections" dialog box, select

"Network Connections".


Internet Connection Firewall (Windows XP)

3 In the "Network Connections" dialog box, right-click on the local area connection entry for your network; this will display a menu. Select the "Properties" menu entry.

4 In the "Local Area Connection Properties" dialog box, select the "Advanced" tab. Disable the Internet Connection Firewall by de-selecting the entry with the following label:"Protect my computer and network by limiting or preventing access to the computer from the Internet".

5 Click "OK".


Documents

DO-009103-TC-6