[src/trunk]: src/sys/netinet6 sync with current code. now IMPLEMENTATION doc ...

[itojun <itojun%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/72f0a83c9789
branches:  trunk
changeset: 481493:72f0a83c9789
user:      itojun <itojun%NetBSD.org@localhost>
date:      Tue Feb 01 00:15:22 2000 +0000

description:
sync with current code. now IMPLEMENTATION doc is almost identical
to the latest KAME one.

diffstat:

 sys/netinet6/IMPLEMENTATION |  416 ++++++++++++++++++++++++++-----------------
 sys/netinet6/TODO           |   43 +---
 2 files changed, 257 insertions(+), 202 deletions(-)

diffs (truncated from 775 to 300 lines):

diff -r f3c066806d7c -r 72f0a83c9789 sys/netinet6/IMPLEMENTATION
--- a/sys/netinet6/IMPLEMENTATION       Tue Feb 01 00:07:50 2000 +0000
+++ b/sys/netinet6/IMPLEMENTATION       Tue Feb 01 00:15:22 2000 +0000
@@ -1,14 +1,14 @@
-$NetBSD: IMPLEMENTATION,v 1.4 2000/01/06 15:48:07 itojun Exp $
+$NetBSD: IMPLEMENTATION,v 1.5 2000/02/01 00:15:22 itojun Exp $
 
 # NOTE: this is from original KAME distribution.
 # Some portion of this document is not applicable to the code merged into
-# NetBSD-current.  Check sys/netinet6/TODO as well.
+# NetBSD-current (for example, section 5).  Check sys/netinet6/TODO as well.
 
                        Implementation Note
 
                        KAME Project
                        http://www.kame.net/
-                       Date: 2000/01/04 17:56:28
+                       Date: 2000/01/30 09:35:41
 
 1. IPv6
 
@@ -20,7 +20,7 @@
 For details please refer to specific chapter in the document, RFCs, manpages
 come with KAME, or comments in the source code.
 
-Conformance tests have been performed on the KAME STABLE kit
+Conformance tests have been performed on past and latest KAME STABLE kit,
 at TAHI project.  Results can be viewed at http://www.tahi.org/report/KAME/.
 We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
 in the past, with our past snapshots.
@@ -88,6 +88,9 @@
     * See 1.7 in this document for details.
 RFC2710: Multicast Listener Discovery for IPv6
 RFC2711: IPv6 router alert option
+RFC2732: Format for Literal IPv6 Addresses in URL's
+    * The spec is implemented in programs that handle URLs
+      (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
 draft-ietf-ipngwg-router-renum-08: Router renumbering for IPv6
 draft-ietf-ipngwg-icmp-namelookups-02: IPv6 Name Lookups Through ICMP
 draft-ietf-ipngwg-icmp-name-lookups-03: IPv6 Name Lookups Through ICMP
@@ -103,6 +106,10 @@
     * See 1.6 in this document for details.
 draft-ietf-ipngwg-scopedaddr-format-00.txt:
        An Extension of Format for IPv6 Scoped Addresses
+draft-ietf-ngtrans-tcpudp-relay-00.txt:
+       An IPv6-to-IPv4 transport relay translator
+    * FAITH tcp relay translator (faithd) implements this.  See 3.1 for more
+      details.
 
 1.2 Neighbor Discovery
 
@@ -112,13 +119,22 @@
 Advertisement support in the kernel and Unsolicited Neighbor Advertisement
 transmission command as admin tool.
 
+Duplicated Address Detection (DAD) will be performed when an IPv6 address
+is assigned to a network interface, or the network interface is enabled
+(ifconfig up).  It is documented in RFC2462 5.4.
 If DAD fails, the address will be marked "duplicated" and message will be
 generated to syslog (and usually to console).  The "duplicated" mark
 can be checked with ifconfig.  It is administrators' responsibility to check
-for and recover from DAD failures.
-The behavior should be improved in the near future.
+for and recover from DAD failures.  We may try to improve failure recovery
+in future KAME code.
+DAD procedure may not be effective on certain network interfaces/drivers.
+If a network driver needs long initialization time (with wireless network
+interfaces this situation is popular), and the driver mistakingly raises
+IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
+DAD probes to not-really-ready network driver and the packet will not go out
+from the interface.  In such cases, network drivers should be corrected.
 
-Some of the network driver loops multicast packets back to itself,
+Some of network drivers loop multicast packets back to themselves,
 even if instructed not to do so (especially in promiscuous mode).
 In such cases DAD may fail, because DAD engine sees inbound NS packet
 (actually from the node itself) and considers it as a sign of duplicate.
@@ -137,10 +153,11 @@
 thread started from (IPng 7155), dated Feb 6 1999.
 
 IPv6 on-link determination rule (RFC2461) is quite different from assumptions
-in BSD network code.  At this moment, KAME does not implement on-link
-determination rule when default router list is empty (RFC2461, section 5.2,
-last sentence in 2nd paragraph - note that the spec misuse the word "host"
-and "node" in several places in the section).
+in BSD IPv4 network code.  To implement behavior in RFC2461 section 5.2
+(when default router list is empty), the kernel needs to know the default
+outgoing interface.  To configure the default outgoing interface, use
+commands like "ndp -I de0" as root.  Note that the spec misuse the word
+"host" and "node" in several places in the section.
 
 To avoid possible DoS attacks and infinite loops, KAME stack will accept
 only 10 options on ND packet.  Therefore, if you have 20 prefix options
@@ -151,30 +168,36 @@
 
 1.3 Scope Index
 
-IPv6 uses scoped addresses.  Therefore, it is very important to
+IPv6 uses scoped addresses.  It is therefore very important to
 specify scope index (interface index for link-local address, or
 site index for site-local address) with an IPv6 address.  Without
-scope index, scoped IPv6 address is ambiguous to the kernel, and
-kernel will not be able to determine the outbound interface for a
-packet.
+scope index, a scoped IPv6 address is ambiguous to the kernel, and
+the kernel will not be able to determine the outbound interface for a
+packet.  KAME code tries to address the issue in several ways.
 
-Ordinary userland applications should use advanced API (RFC2292) to
-specify scope index, or interface index.  For similar purpose,
-sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553.
-However, the semantics for sin6_scope_id is rather vague.  If you
-care about portability of your application, we suggest you to use
-advanced API rather than sin6_scope_id.
+1.3.1 Kernel internal
 
-In the kernel, an interface index for link-local scoped address is
-embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address.
+In the kernel, the interface index for a link-local scope address is
+embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
+address.
 For example, you may see something like:
        fe80:1::200:f8ff:fe01:6317
 in the routing table and interface address structure (struct
-in6_ifaddr).  The address above is a link-local unicast address
+in6_ifaddr). The address above is a link-local unicast address
 which belongs to a network interface whose interface identifier is 1.
 The embedded index enables us to identify IPv6 link local
 addresses over multiple interfaces effectively and with only a
 little code change.
+
+1.3.2 Interaction with API
+
+Ordinary userland applications should use the advanced API (RFC2292)
+to specify scope index, or interface index.  For the similar purpose,
+the sin6_scope_id member in the sockaddr_in6 structure is defined in
+RFC2553.  However, the semantics for sin6_scope_id is rather vague.
+If you care about portability of your application, we suggest you to
+use the advanced API rather than sin6_scope_id.
+
 Routing daemons and configuration programs, like route6d and
 ifconfig, will need to manipulate the "embedded" scope index.
 These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6)
@@ -183,6 +206,26 @@
 Programs that use these APIs have to be prepared about differences
 in kernels anyway.
 
+getaddrinfo(3) and getnameinfo(3) are modified to support extended numeric
+IPv6 syntax, as documented in draft-ietf-ipngwg-scopedaddr-format-00.txt.
+You can specify outgoing link, by using name of the outgoing interface
+like "fe80::1@ne0".  This way you will be able to specify link-local scoped
+address without much trouble.
+To use this extension in your program, you'll need to use getaddrinfo(3),
+and getnameinfo(3) with NI_WITHSCOPEID.
+The implementation currently assumes 1-to-1 relationship between a link and an
+interface, which is stronger than what IPv6 specs say.
+Other APIs like inet_pton(3) or getipnodebyname(3) are inherently unfriendly
+with scoped addresses, since they are unable to annotate addresses with
+scope identifier.
+
+1.3.3 Interaction with users (command line)
+
+Some of the userland tools support extended numeric IPv6 syntax, as
+documented in draft-ietf-ipngwg-scopedaddr-format-00.txt.  In this case,
+you can specify outgoing link, by using name of the outgoing interface like
+"fe80::1@ne0".
+
 When you specify scoped address to the command line, NEVER write the
 embedded form (such as ff02:1::1 or fe80:2::fedc).  This is not supposed
 to work.  Always use standard form, like ff02::1 or fe80::fedc, with
@@ -192,15 +235,14 @@
 This may seem to be opposite from IPv6's premise to support "dentist office"
 situation.  We believe that specifications need some improvements for this.
 
-Some of the userland tools support extended numeric IPv6 syntax, as
-documented in draft-ietf-ipngwg-scopedaddr-format-00.txt.  You can specify
-outgoing link, by using name of the outgoing interface like "fe80::1@ne0".
-This way you will be able to specify link-local scoped address without much
-trouble.
-To use this extension in your program, you'll need to use getaddrinfo(3),
-and getnameinfo(3) with NI_WITHSCOPEID.
-The implementation currently assumes 1-to-1 relationship between a link and an
-interface, which is stronger than what specs say.
+The only exception to the above rule would be when you configure routing table
+manually by route(8).  Gateway portion of IPv6 routing entry must be an
+link-local address (otherwise ICMPv6 redirect will not work), and in this
+case you'll need to configure it by putting interface index into the address:
+       # route add -inet6 default fe80:2::9876:5432:1234:5678
+       (when interface index for outgoing interface = 2)
+To avoid configuration mistakes, we suggest you to run dynamic routing instead
+(like route6d(8)).
 
 1.4 Plug and Play
 
@@ -223,8 +265,8 @@
 
 Internet6:
 Destination                   Gateway                   Flags      Netif Expire
-fe80:1::/64                   link#1                    UC           ed0
-fe80:2::/64                   link#2                    UC           ep0
+fe80::@ed0/64                 link#1                    UC           ed0
+fe80::@ep0/64                 link#2                    UC           ep0
 
 Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
 interfaces, or ppp interfaces) will borrow IEEE802 address from other
@@ -253,6 +295,14 @@
 not forward the packets.  net.inet6.ip6.forwarding defines whether this
 node is router or host (router if it is 1, host if it is 0).
 
+It is NOT recommended to change net.inet6.ip6.forwarding while the node
+is in operation.   IPv6 specification defines behavior for "host" and "router"
+quite differently, and switching from one to another can cause serious
+troubles.  It is recommended to configure the variable at bootstrap time only.
+
+The first step in stateless address configuration is Duplicated Address
+Detection (DAD).  See 1.2 for more detail on DAD.
+
 When a host hears Router Advertisement from the router, a host may
 autoconfigure itself by stateless address autoconfiguration.
 This behavior can be controlled by net.inet6.ip6.accept_rtadv
@@ -330,7 +380,7 @@
 of tunnels, and gif(4) manpage for how to configure.
 
 If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
-read gif(4) carefully.  You will need to remove IPv6 link-local address
+read gif(4) carefully.  You may need to remove IPv6 link-local address
 automatically assigned to the gif interface.
 
 1.6 Source Address Selection
@@ -643,8 +693,7 @@
 The platforms do not support IPv4 mapped address at all (both listening side
 and initiating side).  AF_INET6 and AF_INET sockets are totally separated.
 
-Port number space is totally separate between AF_INET and
-AF_INET6 sockets. 
+Port number space is totally separate between AF_INET and AF_INET6 sockets. 
 
 1.12.2 KAME/FreeBSD3x
 
@@ -672,7 +721,7 @@
 
 (XXX need checking)
 
-1.12.2.1 KAME/FreeBSD3x, initiating side
+1.12.2.2 KAME/FreeBSD3x, initiating side
 
 KAME/FreeBSD3x supports outgoing connetion to IPv4 mapped address
 (::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
@@ -680,14 +729,14 @@
 
 (XXX need checking)
 
-1.12.4 KAME/NetBSD
+1.12.3 KAME/NetBSD
 
 KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
 udp4/6 code (from sys/netinet/udp*).  The implementation is made differently
 from KAME/FreeBSD3x.  KAME/NetBSD uses separate inpcb/in6pcb structures,
 while KAME/FreeBSD3x uses merged inpcb structure.
 
-1.12.4.1 KAME/NetBSD, listening side
+1.12.3.1 KAME/NetBSD, listening side
 
 The platform can be configured to support IPv4 mapped address/special AF_INET6
 wildcard bind (disabled by default).  Kernel behavior can be summarized as
@@ -712,21 +761,21 @@
   getsockopt(IPV6_BINDV6ONLY) returns 0.
 There's no problem with open/close ordering.
 
-1.12.4.1 KAME/NetBSD, initiating side
+1.12.3.2 KAME/NetBSD, initiating side
 
 When you initiate a connection, you can always connect to IPv4 destination
 over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
 This is enabled independently from the configuration for listening side, and
 always enabled.
 
-1.12.5 KAME/BSDI4
+1.12.4 KAME/BSDI4
 
 KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
 which was derived from NRL IPv6/IPsec stack.  I guess it supports IPv4 mapped
 address and speical AF_INET6 wildcard bind.  The implementation is, again,
 different from other KAME/*BSDs.
 
-1.12.5.1 KAME/BSDI4, listening side
+1.12.4.1 KAME/BSDI4, listening side
 
 NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
 It grabs IPv4 connection under certain condition.  NRL inpcb layer has
@@ -738,17 +787,17 @@
   both will success.  However, all IPv4 traffic (and IPv6 traffic) will be
   captured by IPv6 wildcard socket.
 
-1.12.5.2 KAME/BSDI4, initiating side
+1.12.4.2 KAME/BSDI4, initiating side
 
 KAME/BSDi4 supports connection initiation to IPv4 mapped address
 (like ::ffff:10.1.1.1).