sync with latest kame doc. wording changes and updates

1 files changed, 151 insertions, 52 deletions

diff --git a/share/man/man4/inet6.4 b/share/man/man4/inet6.4
index 785678c..cbb5f73 100644
--- a/share/man/man4/inet6.4
+++ b/share/man/man4/inet6.4
@@ -1,6 +1,9 @@
+.\"	$FreeBSD$
+.\"	$KAME: inet6.4,v 1.16 2000/07/05 08:18:42 itojun Exp $
+.\"
 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
 .\" All rights reserved.
-.\" 
+.\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -12,7 +15,7 @@
 .\" 3. Neither the name of the project nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
-.\" 
+.\"
 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
@@ -25,9 +28,6 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$Id: inet6.4,v 1.1.1.1 1999/08/08 23:30:37 itojun Exp $
-.\"     $FreeBSD$
-.\"
 .Dd January 29, 1999
 .Dt INET6 4
 .Os
@@ -53,7 +53,7 @@ implements Internet Protocol version 6.
 is a collection of protocols layered atop the
 .Em Internet Protocol version 6
 .Pq Tn IPv6
-network layer, and utilizing the IPv6 address format.
+transport layer, and utilizing the IPv6 address format.
 The
 .Nm
 family provides protocol support for the
@@ -66,7 +66,7 @@ interface provides access to the
 .Tn IPv6
 protocol.
 .Sh ADDRESSING
-IPv6 addresses are 16 byte quantities, stored in network standard format.
+IPv6 addresses are 16 byte quantities, stored in network standard byteorder.
 The include file
 .Aq Pa netinet/in.h
 defines this address
@@ -77,8 +77,8 @@ Sockets bound to the
 family utilize the following addressing structure,
 .Bd -literal -offset indent
 struct sockaddr_in6 {
-	u_char		sin6_len;
-	u_char		sin6_family;
+	u_int8_t	sin6_len;
+	u_int8_t	sin6_family;
 	u_int16_t	sin6_port;
 	u_int32_t	sin6_flowinfo;
 	struct in6_addr	sin6_addr;
@@ -94,7 +94,7 @@ which is equal to IPv6 address
 .Pc
 to effect
 .Dq wildcard
-matching on incoming messages. 
+matching on incoming messages.
 The address in a
 .Xr connect 2
 or
@@ -103,68 +103,65 @@ call may be given as
 .Dq Dv ::
 to mean
 .Dq this host .
-The address
 .Dq Dv ::
-can be obtained by setting the
+can be obtained by setting
 .Dv sin6_addr
-field to 0, or by using the address contained in the variable
+field into 0, or by using the address contained in variable
 .Dv in6addr_any .
 .Pp
-IPv6 defines scoped addresses such as link-local or site-local addresses.
+IPv6 specification defines scoped address,
+like link-local or site-local address.
 A scoped address is ambiguous to the kernel,
-if it is specified without a scope identifier.
+if it is specified without scope identifier.
 To manipulate scoped addresses properly from the userland,
-programs must use the advanced API defined in RFC2292.
-A compact description on the advanced API is available in
+programs must use advanced API defined in RFC2292.
+Compact description on the advanced API is available in
 .Xr ip6 4 .
 If scoped addresses are specified without explicit scope,
-and the IPv6 default interface for scoped addresses is not specified,
-an error,
-.Er EHOSTUNREACH ,
-will be returned from the kernel.
-Note that scoped addresses are not for common use at this moment,
+the kernel may raise error.
+Note that scoped addresses are not for daily use at this moment,
 both from specification and implementation point of view.
 .Pp
-FreeBSD's IPv6 implementation supports extended numeric IPv6 address 
-notation for link-local addresses,
+KAME implementation supports extended numeric IPv6 address notation
+for link-local addresses,
 like
 .Dq Li fe80::1%de0
 to specify
 .Do
 .Li fe80::1
-on the
+on
 .Li de0
 interface
 .Dc .
-This notation is supported by
+The notation is supported by
 .Xr getaddrinfo 3
 and
 .Xr getnameinfo 3 .
-Some of the normal userland programs, such as
+Some of normal userland programs, such as
 .Xr telnet 1
 or
-.Xr ftp 8 ,
-are able to use this notation.
-With some special programs such as
+.Xr ftp 1 ,
+are able to use the notation.
+With special programs
+like
 .Xr ping6 8 ,
-you can specify an outgoing interface by an extra command line option
+you can specify outgoing interface by extra command line option
 to disambiguate scoped addresses.
 .Pp
 Scoped addresses are handled specially in the kernel.
-Scoped addresses will have their interface indices embedded into the address,
-in the routing table or interface structures.
+In the kernel structures like routing tables or interface structure,
+scoped addresses will have its interface index embedded into the address.
 Therefore,
-a scoped address may have a different representation in the kernel
-than on the wire.
-The embedded index will be visible in
+the address on some of the kernel structure is not the same as that on the wire.
+The embedded index will become visible on
 .Dv PF_ROUTE
-sockets, kernel memory accesses via
+socket, kernel memory accesses via
 .Xr kvm 3
 and some other occasions.
 HOWEVER, users should never use the embedded form.
-For details, please consult
+For details please consult
 .Pa IMPLEMENTATION
-supplied with the KAME kit.
+supplied with KAME kit.
 .Sh PROTOCOLS
 The
 .Nm
@@ -414,7 +411,108 @@ mapped address on
 .Dv AF_INET6
 sockets.
 Defaults to on.
+.It Dv IPV6CTL_RTEXPIRE
+.Pq ip6.rtexpire
+Integer: lifetime in seconds of protocol-cloned
+.Tn IP
+routes after the last reference drops (default one hour).
+.\"This value varies dynamically as described above.
+.It Dv IPV6CTL_RTMINEXPIRE
+.Pq ip6.rtminexpire
+Integer: minimum value of ip.rtexpire (default ten seconds).
+.\"This value has no effect on user modifications, but restricts the dynamic
+.\"adaptation described above.
+.It Dv IPV6CTL_RTMAXCACHE
+.Pq ip6.rtmaxcache
+Integer: trigger level of cached, unreferenced, protocol-cloned routes
+which initiates dynamic adaptation (default 128).
 .El
+.Ss Interaction between IPv4/v6 sockets
+The behavior of 
+.Dv AF_INET6
+TCP/UDP socket is documented in RFC2553.
+Basically, it says as follows:
+.Bl -bullet -compact
+.It
+Specific bind on
+.Dv AF_INET6
+socket
+.Po
+.Xr bind 2
+with address specified
+.Pc
+should accept IPv6 traffic to that address only.
+.It
+If you perform wildcard bind
+on
+.Dv AF_INET6
+socket
+.Po
+.Xr bind 2
+to IPv6 address
+.Li ::
+.Pc ,
+and there is no wildcard bind
+.Dv AF_INET
+socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
+should be routed to that
+.Dv AF_INET6
+socket.
+IPv4 traffic should be seen as if it came from IPv6 address like
+.Li ::ffff:10.1.1.1 .
+This is called IPv4 mapped address.
+.It
+If there are both wildcard bind
+.Dv AF_INET
+socket and wildcard bind
+.Dv AF_INET6
+socket on one TCP/UDP port, they should behave separately.
+IPv4 traffic should be routed to
+.Dv AF_INET
+socket and IPv6 should be routed to
+.Dv AF_INET6
+socket.
+.El
+.Pp
+However, RFC2553 does not define the constraint between the order of
+.Xr bind 2 ,
+nor how IPv4 TCP/UDP port number and IPv6 TCP/UDP port number
+relate each other
+.Po
+should they be integrated or separated
+.Pc .
+Implemented behavior is very different across kernel to kernel.
+Therefore, it is unwise to rely too much upon the behavior of
+.Dv AF_INET6
+wildcard bind socket.
+It is recommended to listen to two sockets, one for
+.Dv AF_INET
+and another for
+.Dv AF_INET6 ,
+when you would like to accept both IPv4 and IPv6 traffic.
+.Pp
+It should also be noted that
+malicious parties can take advantage of the complexity presented above,
+and are able to bypass access control,
+if the target node routes IPv4 traffic to
+.Dv AF_INET6
+socket.
+Users are advised to take caution handling connections
+from IPv4 mapped address to
+.Dv AF_INET6
+sockets.
+.\".Pp
+.\"Because of the above, by default,
+.\"KAME/NetBSD and KAME/OpenBSD
+.\"does not route IPv4 traffic to
+.\".Dv AF_INET6
+.\"socket.
+.\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
+.\"On KAME/NetBSD, IPv4 traffic may be routed with certain
+.\"per-socket/per-node configuration, however, it is not recommended.
+.\"Consult
+.\".Xr ip6 4
+.\"for details.
 .Sh SEE ALSO
 .Xr ioctl 2 ,
 .Xr socket 2 ,
@@ -425,28 +523,29 @@ Defaults to on.
 .Xr tcp 4 ,
 .Xr ttcp 4 ,
 .Xr udp 4
-.Sh CAVEAT
-The IPv6 support is subject to change as the Internet protocols develop.
-Users should not depend on details of the current implementation,
-but rather the services exported.
-.Pp
-Users are suggested to implement
-.Dq version independent
-code as much as possible, as you will need to support both
-.Xr inet 4
-and
-.Nm inet6 .
 .Sh STANDARDS
 .Rs
 .%A Tatsuya Jinmei
 .%A Atsushi Onoe
 .%T "An Extension of Format for IPv6 Scoped Addresses"
 .%R internet draft
-.%N draft-ietf-ipngwg-scopedaddr-format-00.txt
+.%D June 2000
+.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 .%O work in progress material
 .Re
 .Sh HISTORY
 The
 .Nm
-IPv6 APIs are defined in RFC2553 and RFC2292.
+protocol interface are defined in RFC2553 and RFC2292.
 The implementation described herein appeared in WIDE/KAME project.
+.Sh BUGS
+The IPv6 support is subject to change as the Internet protocols develop.
+Users should not depend on details of the current implementation,
+but rather the services exported.
+.Pp
+Users are suggested to implement
+.Dq version independent
+code as much as possible, as you will need to support both
+.Xr inet 4
+and
+.Nm inet6 .