Microsoft Research IPv6 Release

Microsoft Research IPv6 Release 1.4

January 13, 2000 (Check here for the latest version.)

The information in this file applies to both the source and binary-only distributions of this release.

New for Release 1.4

The most pervasive change we've made with this release adds full support for scoped addresses throughout the stack. This improvement is made visible at user level by the addition of new scope-aware APIs (e.g. getaddrinfo, getnameinfo) as recommended by the IETF in RFC 2553. As an example of these, we have updated the ttcp demonstration program to be protocol independent. We've also implemented Nordmark's site-prefixes draft, which allows site-local addresses to be placed in the DNS. We support multi-sited nodes. Note that since these API changes included the addition of a new field to the IPv6 socket address structure, binaries from previous releases will not work with this one. If you have your own applications, they must be recompiled. The new sin6_scope_id field must be initialized; the best way to do this is to set the entire sockaddr structure to zero before use: memset(&sin6, 0, sizeof(struct sockaddr_sin6)).

Our syntax for a literal IPv6 address with scope-id is "scope-id/address". For example, 5/fe80::260:8ff:fe16:6e15 where 5 is an interface index because it's a link-local address. getaddrinfo parses this syntax.

Another major stack improvement is Plug and Play and Power Management support for Windows 2000. USB and PCMCIA network interfaces can now be added to or removed from the system on the fly and the stack will reconfigure itself accordingly. Similarly, you can disconnect and reconnect network links or hibernate and resume your system and the MSR IPv6 stack will do the right thing. You can even dynamically unload and reload the stack without rebooting.

There is a new 6to4cfg program that automates 6to4 configuration. 6to4cfg makes it very easy to setup a 6to4 gateway router and connect your site to the 6bone via 6to4. See our 6to4 documentation.

There are plenty of minor improvements and fixes. We've improved our support for multicast (MLD) and anycast. We've implemented the UDP lite proposal. And we've fixed some problems with our existing correspondent node support (for mobile IP) and the Network Address and Protocol Translator.

We've reorganized our header files so that you can build user-level applications that use IPv6 without needing the SDK or DDK. Our own source tree still requires the SDK and DDK.

Upgrading

If you currently have a previous release installed, uninstall it before installing this one.

To uninstall on NT 4, go to the Control Panel's "Network" applet (an alternative way to do this is to right-click on "Network Neighborhood" and select "Properties") and select the "Protocols" tab. Select the IPv6 Protocol from the list and click "Remove".

To uninstall on Windows 2000, go to the Control Panel's "Network Connections" panel (an alternative way to do this is to right-click on "My Network Places" and select "Properties") and right-click on the "Local Area Connection". Choose "Properties". Go to the "General" tab. Select the IPv6 Protocol and then click on "Uninstall". Note that the user interface for Windows 2000 differs slightly from beta to beta, so these instructions are approximate.

System Requirements

Most of our testing has been performed on Windows 2000 and Windows NT 4.0 with Service Pack 3 or later installed. Our implementation should work on NT 4.0 at any Service Pack level; however, we haven't tested all cases. For those who are members of the Windows 2000 Beta program, we also work on Windows 2000 build 1773 or later (this includes all the release candidates and beta versions except Beta 1). The same binaries that run on NT 4.0 also run on Windows 2000; only the installation changes.

If you plan to run our stack on an existing NT 4.0 system, we recommend that you update it to the latest Service Pack level. Service Pack updates are available for free download from http://support.microsoft.com/Support/NTServer/Content/ServicePacks/default.asp.

The binary form of this release is only available for the Intel x86 architecture, which is also the only NT-supported platform we've tested on.

We currently have support for Ethernet and FDDI interfaces. Any Ethernet or FDDI card that is supported by NT 4.0 should work with our release, however, we've only tested about a dozen Ethernet cards and one FDDI card.

[If you have the binary-only distribution, you can skip down to Installation]

Building

The build environment for the source distribution is that provided by the Microsoft Windows NT Version 4.0 Device Driver Kit (DDK), which in turn requires a machine with Windows NT 4.0, the Platform Software Development Kit (SDK) for Win32 and Visual C++ 5.0 (or an equivalent 32-bit C compiler) installed.

If you do not have some of these tools and wish to acquire them, you will need to join Microsoft's Developer Network (MSDN) at the Professional Subscription level or greater. Please see http://msdn.microsoft.com/developer/default.htm for more information. Educational institutions may be eligible for special academic prices, please see your local academic reseller for pricing and availability.

Most of our development has occurred on machines running NT 4.0 w/ SP3 or later, Visual C++ 5.0 or 6.0, Platform SDK of Oct '97, and the NT DDK Version 4.0. Having precisely these same versions of the compiler and SDK shouldn't be necessary; however, we haven't done extensive testing of other configurations.

Assuming you have the DDK build environment set up correctly (test by building one or more of the samples included in the DDK), building our entire tree can be accomplished simply by running "build" in the msripv6 directory. To build just a single component, cd to that component's directory and run build there. For example, to build the core IPv6 stack, run build in the msripv6\tcpip6 directory. The resulting binary is tcpip6.sys.

(Build likes to complain about include files that don't end with a blank line and include files it can't find directly. You can ignore these messages)

Creating an Install Kit

Once you have successfully built the tree as described above, you can package up an IPv6 install kit for easy installation of the associated parts. To do this, go to the kit subdirectory of msripv6. Run the mkkit.cmd script with the path to an existing directory in which to place the completed kit as an argument (for example, "mkkit C:\Ipv6Kit").

Installation on NT 4.0

The same procedure is used to install either our binary distribution or a version you built yourself from our source distribution. Start the Control Panel's "Network" applet (an alternative way to do this is to right-click on "Network Neighborhood" and select "Properties") and select the "Protocols" tab. Click the "Add..." button and then "Have Disk...". When it asks you for a disk, give it the full pathname to where you downloaded our binary distribution kit (or where you placed the kit you created yourself -- in the example above, this was "C:\IPv6Kit"). IPv6 should now install itself.

The above install procedure will copy the files from the install kit into the appropriate places and add entries to the system registry for IPv6 configuration. If you later modify IPv6 components, you can replace just the affected file or files without having to uninstall/install IPv6 again. The protocol stack itself (tcpip6.sys) is installed in your %SystemRoot%\system32\drivers directory. The Winsock helper dynamically linked library for the INET6 address family (wship6.dll) and all the user apps and utilities (ipv6.exe, ping6.exe, tracert6.exe, ttcp.exe, etc) live in the %SystemRoot%\system32 directory.

Installation on Windows 2000

The same procedure is used to install either our binary distribution or a version you built yourself from our source distribution. Note that the user interface for Windows 2000 differs slightly from beta to beta, so these instructions are approximate.

Go to the Control Panel's "Network Connections" panel (an alternative way to do this is to right-click on "My Network Places" and select "Properties") and right-click on the "Local Area Connection". Choose "Properties". Go to the "General" tab. Click on "Add". Choose "Protocol" and click on "Add". Click on "Have Disk...". When it asks you for a disk, give it the full pathname to where you downloaded our binary distribution kit (or where you placed the kit you created yourself -- in the example above, this was "C:\IPv6Kit"). IPv6 should now install itself.

Note that unlike NT 4, you do not have to reboot at this point. IPv6 starts immediately once installed.

The above install procedure will copy the files from the install kit into the appropriate places and add entries to the system registry for IPv6 configuration. If you later modify IPv6 components, you can replace just the affected file or files without having to uninstall/install IPv6 again. The protocol stack itself (tcpip6.sys) is installed in your %SystemRoot%\system32\drivers directory. The Winsock helper dynamically linked library for the INET6 address family (wship6.dll) and all the user apps and utilities (ipv6.exe, ping6.exe, tracert6.exe, ttcp.exe, etc) live in the %SystemRoot%\system32 directory.

Configuration

Our implementation supports stateless address autoconfiguration. In the common case, you won't need to perform any manual configuration. At boot time, a link-local address will automatically be assigned to each network interface. Global addresses will be assigned based upon receipt of router advertisements. The default IPSec policy is to allow all traffic to bypass authentication checks.

Some manual configuration is required for more advanced features. We have extra information files describing these in the docs subdirectory of the distribution tree. In particular, we have pages describing how to set up a connection to the 6bone or a 6to4 gateway, the use of the ipv6 command to configure interfaces, addresses, and routing, and how to configure IP security.

Utilities

We wrote a utility (ipv6.exe) to retrieve and display various types of information from the stack. You can use this to view the state of interfaces, the neighbor cache, binding cache, destination cache (called the route cache in our implementation), and the route table. This utility can also be used to manually configure interfaces, addresses and route table entries.

There are also two separate utilities (ipsecgui.exe and ipsec.exe) for configuring IPSec policies and associations.

Also included with this release are ping6, tracert6, and ttcp. These work similarly to their v4 counterparts and are installed into %SystemRoot%\system32 by the above installation procedure. The ttcp utility now supports IPv4 as well. We also include mldtest and testsend in the binary distribution, but they are not installed anywhere by default.

Implementers may be interested in our hrdtest utility, which generates packets with various combinations (both legal and not) of IPv6 extension headers.

Enabling IPv6 Capability for Microsoft Internet Explorer

We include a binary of wininet.dll for NT 4.0 that makes IE 4.01 SP1 cognizant of IPv6. In our very brief testing, it appeared to work with IE 5 as well.

One caveat is that changing your existing wininet.dll to our version may break something else; we haven't tested this as extensively as the real product. In fact, we've only tested basic web browsing with http and ftp URLS. We recommend you save your existing version in case you need to back out of this change. We only have a modified wininet.dll for NT 4.0 at the moment; this will not work on Windows 2000.

To install, rename your existing wininet.dll to something else (e.g. wininet.old) and copy our wininet.dll to %SystemRoot%\system32\wininet.dll and reboot. The rename step is important since you can't overwrite an in-use dll.

Note you also need the fixes to afd.sys and (on pre-SP4 systems) msafd.dll mentioned below for this to work.

Internet Explorer understands the RFC 2732 syntax for embedding IPv6 literal addresses in URLs. For example, http://[2002:836b:4179::836b:4179] as well as http://ipv6.research.microsoft.com. However, Internet Explorer does not yet support the use of scope-ids with embedded IPv6 literal addresses.

Fixes for NT 4.0

The following are problems with NT 4.0 that were only exposed by running IPv6. We include binaries with our release that fix these problems. We don't want to get in the business of tracking all fixes to NT, however, so most of our binaries are at the base level of NT 4.0 (i.e. no Service Packs installed). Some Service Packs also include new versions of some or all of these binaries, which presumably fix other problems (and not these). In other words, if you already have one or more Service Packs installed, installing these binaries may break something else. For this reason, these binaries are not installed automatically along with IPv6 and instead must be installed by hand. You get to decide if the fix is worth the risk.

The good news it that most of these problems have since been fixed in Service Pack 4 (and later) for NT 4.0 and in Windows 2000.

There is protocol specific code in afd.sys to which we had to add an IPv6 case. Rename your existing version to something else and copy our afd.sys (for NT 4.0 with SP3 or less) or afd.sp4 (for NT 4.0 SP4 or later) to %SystemRoot%\system32\drivers\afd.sys and reboot. This is fixed in Windows 2000.

The Winsock getsockname call on AF_INET6 sockets triggers a bug in msafd.dll related to the longer addresses. If you decide you wish to fix this (see warning above), rename your existing %SystemRoot%\System32\msafd.dll to something else and replace it with the one we've included in this release. This fix is required for most ftp clients to work properly. This is fixed in SP4 (and later) and in Windows 2000.

The nslookup utility will incorrectly print the results of a AAAA record query (some parts of the address are byte-swapped). If you decide you wish to fix this (see warning above), replace your existing %SystemRoot%\System32\nslookup.exe with the one we've included in this release. This is fixed in SP4 (and later) and in Windows 2000.

Known Issues with our Stack

Most of the Ethernet interface cards we have tried "just worked". In two cases, however, we had to update the drivers to the latest versions available in order to get them to work with our code (we suspect they had problems with multicast that weren't tickled by the IPv4 stack). If you experience an immediate crash upon booting with the IPv6 stack installed, check with your card's manufacturer to ensure that you have the latest driver.

Our IPv6 TCP implementation doesn't have all the post-NT 4.0 fixes and improvements that Microsoft has since shipped in the Service Packs and in Windows 2000.

If you are configuring a router that should forward packets to/from 6to4, configured tunnels, or automatic tunnels, then you must enable forwarding on all 6over4 interfaces.

There is a bug in Windows 2000 name resolution that causes the following problem. If your machine has a v6 address in the DNS, and you try to look it up on the machine itself (eg lookup "aname" while running on aname), then the IPv6 name resolution will fail. (The problem has to do with Netbios name resolution getting in the way.) Qualifying the name (for example using "aname.acompany.com") works around the bug.

Our DNS resolver code understands A and AAAA records but not A6 records. The resolver only uses IPv4 packets to communicate with DNS servers; it can not run over IPv6 even when it is looking up AAAA records. We do not support Dynamic DNS updates.

Mailing List

We have set up a mailing list for interested parties to use in exchanging information regarding their experiences working with our implementation. We will also be making interim announcements regarding the state of our implementation to this list. To join, send an email message to listserv@list.research.microsoft.com containing the text

  • subscribe msripv6-users yourfirstname yourlastname

Daily Code Drops

We make a daily code drop available to those developers who want more timely source updates. Naturally, these drops aren't as polished as our quasi-quarterly releases. If this is something that interests you, drop us a line at the email address below.

Bug Reports/Feedback

We welcome bug reports and other feedback, especially interoperability reports with other IPv6 implementations. Please send email on such subjects to msripv6-bugs@list.research.microsoft.com.

Contact Info

Should you wish to contact us for any reason besides the above mentioned bug reports/feedback, please send email to msripv6@microsoft.com or write Microsoft Research, One Microsoft Way, Redmond, WA 98052-6399.