You are on page 1of 42

ISOS UPnP IGD Feature and Interface Guide

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

Copyright
Copyright 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 noninfringement. 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.

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 GlobespanVirata
For more information on GlobespanVirata, contact the offices below or visit our web site: http://www.globespanvirata.com GlobespanVirata Headquarters 100 Schulz Drive Red Bank, NJ 07701 USA phone: +1-888-855-4562 GlobespanVirata UK Unit 230 Cambridge Science Park Milton Road Cambridge CB4 0WB United Kingdom phone: +44 1223 707400

Trademarks
EmWeb is a registered trademark of GlobespanVirata Inc.

ii

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

Contents
1. About this Guide 1
1.1 Structure of this guide 2 1.2 Typographical conventions 3 1.3 Reading this guide 4 1.4 Conformance 4 1.5 Glossary 5 1.6 Useful Web Sites for UPnP 6 1.7 Related Documentation 6

2. Introduction 9
2.1 ISOS UPnP IGD 10 2.2 The ISOS Internet Gateway Device 11 2.3 Supported Device Types and Services 15

3. ISOS UPnP IGD Configuration 19


3.1 Introduction 20 3.2 Building the ISOS IGD 20 3.3 IGD Configuration 23 3.4 Device Driver Support 26

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


B.1 UPnP on Windows ME 30 B.2 UPnP on Windows XP 30 B.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 6 Table 2: InternetGatewayDevice and Service Support 16 Table 3: WANDevice and Service Support 16 Table 4: WANConnectionDevice and Service Support 17 Table 5: Port Slot Symbols 21

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

List of Tables

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

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

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

List of Figures

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)

Structure of this guide

1.1

Structure of this guide


1.1.1 Scope The 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 Audience This 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 Content GlobespanVirata 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.

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

About this Guide

1.2

Typographical conventions
Throughout this guide, the following typographical conventions are used to denote important information. 1.2.1 Text conventions The 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 Cautions The 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.

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

Reading this guide

1.3

Reading this guide


1.3.1 Providing feedback on this guide Please 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 guide Although 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

Conformance
The 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)

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

About this Guide

1.5

Glossary
The 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. A network device that supports UPnP network communication and provides services and information about the state of the device to control points. Hypertext Markup Language - the language used to create documents for the World Wide Web. Hypertext Transfer Protocol; one of the communication protocols used on the World Wide Web, implemented in the EmWeb Server. The ISOS Internet Gateway Device; the ISOS implementation of the UPnP standard for an Internet gateway device. Local Area Network. Network Address Translation. Transmission Control Protocol / Internet Protocol the set of communication protocols used to connect computers on the Internet. Universal Plug and Play - a device architecture for network communication. Uniform Resource Locator - the network address of documents and other resources on the World Wide Web.

controlled device

HTML HTTP

IGD

LAN NAT TCP/IP

UPnP URL

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

Useful Web Sites for UPnP

WAN XML

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

1.6

Useful Web Sites for UPnP


Web Site http://www.globespanvirata.com Description The GlobespanVirata Web site. The World Wide Web consortium (information about HTTP, HTML, and other standards concerning the World Wide Web). The Universal Plug and Play Forum.

http://www.w3c.org

http://www.upnp.org

http://www.upnp.org/download/UPnPD UPnP Device Architecture specification. A10_20000613 http://www.microsoft.com/hwdev/tech/ Microsoft UPnP device kit. nonpc/UPnP/default.asp http://www.w3c.org/TR/2000/REC-xml- XML specification. 20001006 http://www.w3c.org/TR/1999/REC-xml- XML Namespace specification. names-19990114/ Site maintained by Internet Assigned Number Authority (IANA) at the http://www.isi.edu/in-notes/iana/assign Information Sciences Institute (ISI) of ments/media-types/ the University of Southern California (USC); contains the MIME media types registry

Table 1:

Useful web sites for UPnP

1.7

Related Documentation
This 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.

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

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.

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

Related Documentation

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

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 Feature and Interface Guide DO-009103-PS (Issue 6, 6th Dec 2002)

ISOS UPnP IGD

2.1

ISOS UPnP IGD


An 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). GlobespanViratas 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.)

10

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

Introduction

2.2

The ISOS Internet Gateway Device


The 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 2

Integrate the IGD into your ISOS system. (If you are using the system file supplied by GlobespanVirata, you can skip this step.) 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 GlobespanViratas 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

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

11

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.
LAN device UPnP Control Point UPnP msgs UPnP responses ISOS IGD Incoming msgs Router Outgoing msgs ISP Gateway

2 3

Incoming msgs

Outgoing msgs Responses

Responses

Figure 1 ISOS IGD Communication


1

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.)

12

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

Introduction

When incoming messages are enabled, the gateway device operates as a router, accepting the messages and transmitting them to the LAN. 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.
local device Local Area Network Gateway Device ISOS IGD Ethernet [NAT] [Firewall] local device Internal IP address [Router] [Broadband modem] External IP address DSL Internet Service Provider

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 GlobespanViratas 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.

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

13

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).
Gateway Device ISOS IGD Ethernet Local Area Network Ethernet DSL

local device

[NAT]
[Router, Firewall]

[Bridge]
[Broadband modem]

Internet Service Provider

local device

Internal IP address

External IP address

Figure 3

ISOS IGD (Separate router and broadband modem functions)

14

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

Introduction

2.3

Supported Device Types and Services


At 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.

InternetGatewayDevice WANCommonInterfaceConfig Service

WANDevice

WANConnectionDevice Layer3 Forwarding Service WANDSLLinkConfig or WANEthernetLinkConfig Service

WANIPConnection or WANPPPConnection Service

Figure 4

ISOS IGD Device and Service Hierarchy

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

15

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: InternetGatewayDevice Services Layer3Forwarding Actions State Variables SetDefaultConnectionService DefaultConnectionService GetDefaultConnectionService

Table 2:

InternetGatewayDevice and Service Support

Device Type: WANDevice Services Actions State Variables WANAccessType Layer1UpstreamMaxBitRate WANCommonInterfaceConfig GetCommonLinkProperties Layer1DownstreamMaxBitRate PhysicalLinkStatus

Table 3:

WANDevice and Service Support

16

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

Introduction

Device Type: WANConnectionDevice Services WANDSLLinkConfig WANEthernetLinkConfig Actions SetDSLLinkType GetDSLLinkInfo GetAutoConfig GetEthernetLinkStatus SetConnectionType GetConnectionTypeInfo RequestConnection ForceTermination GetStatusInfo GetNATRSIPStatus GetGenericPortMappingEntry AddPortMapping DeletePortMapping GetExternalIPAddress State Variables LinkType LinkStatus AutoConfig EthernetLinkstatus ConnectionType PossibleConnectionTypes ConnectionStatus Uptime LastConnectionError RSIPAvailable NATEnabled ExternalIPAddress PortMappingNumberOfEntries PortMappingEnabled PortMappingLeaseDuration RemoteHost ExternalPort InternalPort PortMappingProtocol InternalClient PortMappingDescription ConnectionType PossibleConnectionTypes ConnectionStatus Uptime LastConnectionError RSIPAvailable NATEnabled ExternalIPAddress PortMappingNumberOfEntries PortMappingEnabled PortMappingLeaseDuration RemoteHost ExternalPort InternalPort PortMappingProtocol InternalClient PortMappingDescription

WANIPConnection

WANPPPConnection

SetConnectionType GetConnectionTypeInfo RequestConnection ForceTermination GetStatusInfo GetLinkLayerMaxBitRates GetNATRSIPStatus GetGenericPortMappingEntry GetSpecificPortMappingEntry AddPortMapping DeletePortMapping GetExternalIPAddress

Table 4:

WANConnectionDevice and Service Support

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

17

Supported Device Types and Services

18

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

3. ISOS UPnP IGD Configuration

This chapter provides information about building and configuring the IGD.

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

19

Introduction

3.1

Introduction
GlobespanVirata 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 IGD


To 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 Slots The 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.

20

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

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 External DSL ports (maximum) External Ethernet ports (maximum) PPP connections per port (maximum) IP sessions per channel (maximum) Default Value #define IGD_LIMIT_WAN_DEVICE_DSL 1 #define IGD_LIMIT_WAN_DEVICE_ETHERNET 1 #define IGD_LIMIT_WAN_CONNECTION_DEVICE 2 #define IGD_LIMIT_WAN_IP_CONNECTION_SERVICE 1

IP sessions per PPP #define IGD_LIMIT_WAN_PPP_CONNECTION_SERVICE 1 connection (maximum)

Table 5:

Port Slot Symbols

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

21

Building the ISOS IGD

3.2.2

Integrating the IGD into your system To build a system that includes the ISOS Internet Gateway Device capability:
1

Add the following lines to the appropriate system file:


set with_upnp set 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.) Set up your Web Content Compiler license. (See the ISOS document Web Content Compiler Enhanced License (DO-008620-LS).) 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>".

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

22

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

ISOS UPnP IGD Configuration

3.3

IGD Configuration
After 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 Configuration To 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 PCs 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.

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

23

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 Configuration To 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.

24

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

ISOS UPnP IGD Configuration

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 Configuration Use the following Command Line Interface (CLI) commands to perform UPnP configuration for the ISOS IGD: webserver show info webserver set interface webserver 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
ISOS UPnP IGD Feature and Interface Guide DO-009103-PS (Issue 6, 6th Dec 2002) 25

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 Support


If you supply your own device drivers, you must implement support for the following BUN attributes:
Connected

Either LinkSpeed or both RxBitRate and TxBitRate

The LinkSpeed attribute is measured in 100bps. Therefore: bit rate = 100 * LinkSpeed. RxBitRate and TxBitRate are measured in bps.

26

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

A:IGD Device and Service Templates

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

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

27

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/).

28

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

B:UPnP Control Point Software

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

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

29

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 ME
To install the control point software on Windows ME:
1 2

In the Control Panel, select "Add/Remove Programs". In the "Add/Remove Programs Properties" dialog box, select the "Windows Setup" tab. In the "Components" list, double click on the "Communications" entry. In the "Communications" dialog box, scroll down the "Components" list to display the UPnP entry. Select the entry, click "OK". Click "OK" to finish the "Add/Remove Programs" dialog. Reboot your system.

4 5

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 XP
To install the control point software on Windows XP:
1 2

In the Control Panel, select "Add/Remove Programs". In the "Add or Remove Programs" dialog box, click the "Add / Remove Windows Components" button.

30

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

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

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

31

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 window


4

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".

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.

32

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

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 2

In the Control Panel, select "Network and Internet Connections". In the "Network and Internet Connections" dialog box, select "Network Connections".

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

33

Internet Connection Firewall (Windows XP)

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. 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". Click "OK".

34

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