share/man/man4/inet6.4

   1 .\"     $FreeBSD: src/share/man/man4/inet6.4,v 1.4.2.9 2002/05/15 16:45:30 ume Exp $
   2 .\"     $KAME: inet6.4,v 1.21 2001/04/05 01:00:18 itojun Exp $
   3 .\"
   4 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the project nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd January 29, 1999
  32 .Dt INET6 4
  33 .Os
  34 .Sh NAME
  35 .Nm inet6
  36 .Nd Internet protocol version 6 family
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In netinet/in.h
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 family is an updated version of
  44 .Xr inet 4
  45 family.
  46 While
  47 .Xr inet 4
  48 implements Internet Protocol version 4,
  49 .Nm
  50 implements Internet Protocol version 6.
  51 .Pp
  52 .Nm
  53 is a collection of protocols layered atop the
  54 .Em Internet Protocol version 6
  55 .Pq Tn IPv6
  56 transport layer, and utilizing the IPv6 address format.
  57 The
  58 .Nm
  59 family provides protocol support for the
  60 .Dv SOCK_STREAM , SOCK_DGRAM ,
  61 and
  62 .Dv SOCK_RAW
  63 socket types; the
  64 .Dv SOCK_RAW
  65 interface provides access to the
  66 .Tn IPv6
  67 protocol.
  68 .Sh ADDRESSING
  69 IPv6 addresses are 16 byte quantities, stored in network standard byteorder.
  70 The include file
  71 .Aq Pa netinet/in.h
  72 defines this address
  73 as a discriminated union.
  74 .Pp
  75 Sockets bound to the
  76 .Nm
  77 family utilize the following addressing structure:
  78 .Bd -literal -offset indent
  79 struct sockaddr_in6 {
  80         u_int8_t        sin6_len;
  81         u_int8_t        sin6_family;
  82         u_int16_t       sin6_port;
  83         u_int32_t       sin6_flowinfo;
  84         struct in6_addr sin6_addr;
  85         u_int32_t       sin6_scope_id;
  86 };
  87 .Ed
  88 .Pp
  89 Sockets may be created with the local address
  90 .Dq Dv ::
  91 (which is equal to IPv6 address
  92 .Dv 0:0:0:0:0:0:0:0 )
  93 to affect
  94 .Dq wildcard
  95 matching on incoming messages.
  96 .Pp
  97 The IPv6 specification defines scoped addresses,
  98 like link-local or site-local addresses.
  99 A scoped address is ambiguous to the kernel,
 100 if it is specified without a scope identifier.
 101 To manipulate scoped addresses properly from the userland,
 102 programs must use the advanced API defined in RFC2292.
 103 A compact description of the advanced API is available in
 104 .Xr ip6 4 .
 105 If a scoped address is specified without an explicit scope,
 106 the kernel may raise an error.
 107 Note that scoped addresses are not for daily use at this moment,
 108 both from a specification and an implementation point of view.
 109 .Pp
 110 The KAME implementation supports an extended numeric IPv6 address notation
 111 for link-local addresses,
 112 like
 113 .Dq Li fe80::1%de0
 114 to specify
 115 .Do
 116 .Li fe80::1
 117 on
 118 .Li de0
 119 interface
 120 .Dc .
 121 This notation is supported by
 122 .Xr getaddrinfo 3
 123 and
 124 .Xr getnameinfo 3 .
 125 Some of normal userland programs, such as
 126 .Xr telnet 1
 127 or
 128 .Xr ftp 1 ,
 129 are able to use this notation.
 130 With special programs
 131 like
 132 .Xr ping6 8 ,
 133 you can specify the outgoing interface by an extra command line option
 134 to disambiguate scoped addresses.
 135 .Pp
 136 Scoped addresses are handled specially in the kernel.
 137 In kernel structures like routing tables or interface structures,
 138 a scoped address will have its interface index embedded into the address.
 139 Therefore,
 140 the address in some kernel structures is not the same as that on the wire.
 141 The embedded index will become visible through a
 142 .Dv PF_ROUTE
 143 socket, kernel memory accesses via
 144 .Xr kvm 3
 145 and on some other occasions.
 146 HOWEVER, users should never use the embedded form.
 147 For details please consult
 148 .Pa IMPLEMENTATION
 149 supplied with KAME kit.
 150 .Sh PROTOCOLS
 151 The
 152 .Nm
 153 family is comprised of the
 154 .Tn IPv6
 155 network protocol, Internet Control
 156 Message Protocol version 6
 157 .Pq Tn ICMPv6 ,
 158 Transmission Control Protocol
 159 .Pq Tn TCP ,
 160 and User Datagram Protocol
 161 .Pq Tn UDP .
 162 .Tn TCP
 163 is used to support the
 164 .Dv SOCK_STREAM
 165 abstraction while
 166 .Tn UDP
 167 is used to support the
 168 .Dv SOCK_DGRAM
 169 abstraction.
 170 Note that
 171 .Tn TCP
 172 and
 173 .Tn UDP
 174 are common to
 175 .Xr inet 4
 176 and
 177 .Nm .
 178 A raw interface to
 179 .Tn IPv6
 180 is available
 181 by creating an Internet socket of type
 182 .Dv SOCK_RAW .
 183 The
 184 .Tn ICMPv6
 185 message protocol is accessible from a raw socket.
 186 .\" .Pp
 187 .\" The 128-bit IPv6 address contains both network and host parts.
 188 .\" However, direct examination of addresses is discouraged.
 189 .\" For those programs which absolutely need to break addresses
 190 .\" into their component parts, the following
 191 .\" .Xr ioctl 2
 192 .\" commands are provided for a datagram socket in the
 193 .\" .Nm
 194 .\" domain; they have the same form as the
 195 .\" .Dv SIOCIFADDR
 196 .\" command (see
 197 .\" .Xr intro 4 ) .
 198 .\" .Pp
 199 .\" .Bl -tag -width SIOCSIFNETMASK
 200 .\" .It Dv SIOCSIFNETMASK
 201 .\" Set interface network mask.
 202 .\" The network mask defines the network part of the address;
 203 .\" if it contains more of the address than the address type would indicate,
 204 .\" then subnets are in use.
 205 .\" .It Dv SIOCGIFNETMASK
 206 .\" Get interface network mask.
 207 .\" .El
 208 .\" .Sh ROUTING
 209 .\" The current implementation of Internet protocols includes some routing-table
 210 .\" adaptations to provide enhanced caching of certain end-to-end
 211 .\" information necessary for Transaction TCP and Path MTU Discovery.  The
 212 .\" following changes are the most significant:
 213 .\" .Bl -enum
 214 .\" .It
 215 .\" All IP routes, except those with the
 216 .\" .Dv RTF_CLONING
 217 .\" flag and those to multicast destinations, have the
 218 .\" .Dv RTF_PRCLONING
 219 .\" flag forcibly enabled (they are thus said to be
 220 .\" .Dq "protocol cloning" ).
 221 .\" .It
 222 .\" When the last reference to an IP route is dropped, the route is
 223 .\" examined to determine if it was created by cloning such a route.  If
 224 .\" this is the case, the
 225 .\" .Dv RTF_PROTO3
 226 .\" flag is turned on, and the expiration timer is initialized to go off
 227 .\" in net.inet.ip.rtexpire seconds.  If such a route is re-referenced,
 228 .\" the flag and expiration timer are reset.
 229 .\" .It
 230 .\" A kernel timeout runs once every ten minutes, or sooner if there are
 231 .\" soon-to-expire routes in the kernel routing table, and deletes the
 232 .\" expired routes.
 233 .\" .El
 234 .\" .Pp
 235 .\" A dynamic process is in place to modify the value of
 236 .\" net.inet.ip.rtexpire if the number of cached routes grows too large.
 237 .\" If after an expiration run there are still more than
 238 .\" net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire
 239 .\" value is multiplied by 3/4, and any routes which have longer
 240 .\" expiration times have those times adjusted.  This process is damped
 241 .\" somewhat by specification of a minimum rtexpire value
 242 .\" (net.inet.ip.rtminexpire), and by restricting the reduction to once in
 243 .\" a ten-minute period.
 244 .\" .Pp
 245 .\" If some external process deletes the original route from which a
 246 .\" protocol-cloned route was generated, the ``child route'' is deleted.
 247 .\" (This is actually a generic mechanism in the routing code support for
 248 .\" protocol-requested cloning.)
 249 .\" .Pp
 250 .\" No attempt is made to manage routes which were not created by protocol
 251 .\" cloning; these are assumed to be static, under the management of an
 252 .\" external routing process, or under the management of a link layer
 253 .\" (e.g.,
 254 .\" .Tn ARP
 255 .\" for Ethernets).
 256 .\" .Pp
 257 .\" Only certain types of network activity will result in the cloning of a
 258 .\" route using this mechanism.  Specifically, those protocols (such as
 259 .\" .Tn TCP
 260 .\" and
 261 .\" .Tn UDP )
 262 .\" which themselves cache a long-lasting reference to route for a destination
 263 .\" will trigger the mechanism; whereas raw
 264 .\" .Tn IP
 265 .\" packets, whether locally-generated or forwarded, will not.
 266 .Ss MIB Variables
 267 A number of variables are implemented in the net.inet6 branch of the
 268 .Xr sysctl 3
 269 MIB.
 270 In addition to the variables supported by the transport protocols
 271 (for which the respective manual pages may be consulted),
 272 the following general variables are defined:
 273 .Bl -tag -width IPV6CTL_MAXFRAGPACKETS
 274 .It Dv IPV6CTL_FORWARDING
 275 .Pq ip6.forwarding
 276 Boolean: enable/disable forwarding of
 277 .Tn IPv6
 278 packets.
 279 Also, identify if the node is acting as a router.
 280 Defaults to off.
 281 .It Dv IPV6CTL_SENDREDIRECTS
 282 .Pq ip6.redirect
 283 Boolean: enable/disable sending of
 284 .Tn ICMPv6
 285 redirects in response to unforwardable
 286 .Tn IPv6
 287 packets.
 288 This option is ignored unless the node is routing
 289 .Tn IPv6
 290 packets,
 291 and should normally be enabled on all systems.
 292 Defaults to on.
 293 .It Dv IPV6CTL_DEFHLIM
 294 .Pq ip6.hlim
 295 Integer: default hop limit value to use for outgoing
 296 .Tn IPv6
 297 packets.
 298 This value applies to all the transport protocols on top of
 299 .Tn IPv6 .
 300 There are APIs to override the value.
 301 .It Dv IPV6CTL_MAXFRAGPACKETS
 302 .Pq ip6.maxfragpackets
 303 Integer: default maximum number of fragmented packets the node will accept.
 304 0 means that the node will not accept any fragmented packets.
 305 -1 means that the node will accept as many fragmented packets as it receives.
 306 The flag is provided basically for avoiding possible DoS attacks.
 307 .It Dv IPV6CTL_ACCEPT_RTADV
 308 .Pq ip6.accept_rtadv
 309 Boolean: enable/disable receiving of
 310 .Tn ICMPv6
 311 router advertisement packets,
 312 and autoconfiguration of address prefixes and default routers.
 313 The node must be a host
 314 (not a router)
 315 for the option to be meaningful.
 316 Defaults to off.
 317 .It Dv IPV6CTL_KEEPFAITH
 318 .Pq ip6.keepfaith
 319 Boolean: enable/disable
 320 .Dq FAITH
 321 TCP relay IPv6-to-IPv4 translator code in the kernel.
 322 Refer
 323 .Xr faith 4
 324 and
 325 .Xr faithd 8
 326 for detail.
 327 Defaults to off.
 328 .It Dv IPV6CTL_LOG_INTERVAL
 329 .Pq ip6.log_interval
 330 Integer: default interval between
 331 .Tn IPv6
 332 packet forwarding engine log output
 333 (in seconds).
 334 .It Dv IPV6CTL_HDRNESTLIMIT
 335 .Pq ip6.hdrnestlimit
 336 Integer: default number of the maximum
 337 .Tn IPv6
 338 extension headers
 339 permitted on incoming
 340 .Tn IPv6
 341 packets.
 342 If set to 0, the node will accept as many extension headers as possible.
 343 .It Dv IPV6CTL_DAD_COUNT
 344 .Pq ip6.dad_count
 345 Integer: default number of
 346 .Tn IPv6
 347 DAD
 348 .Pq duplicated address detection
 349 probe packets.
 350 The packets will be generated when
 351 .Tn IPv6
 352 interface addresses are configured.
 353 .It Dv IPV6CTL_AUTO_FLOWLABEL
 354 .Pq ip6.auto_flowlabel
 355 Boolean: enable/disable automatic filling of
 356 .Tn IPv6
 357 flowlabel field, for outstanding connected transport protocol packets.
 358 The field might be used by intermediate routers to identify packet flows.
 359 Defaults to on.
 360 .It Dv IPV6CTL_DEFMCASTHLIM
 361 .Pq ip6.defmcasthlim
 362 Integer: default hop limit value for an
 363 .Tn IPv6
 364 multicast packet sourced by the node.
 365 This value applies to all the transport protocols on top of
 366 .Tn IPv6 .
 367 There are APIs to override the value as documented in
 368 .Xr ip6 4 .
 369 .It Dv IPV6CTL_GIF_HLIM
 370 .Pq ip6.gifhlim
 371 Integer: default maximum hop limit value for an
 372 .Tn IPv6
 373 packet generated by
 374 .Xr gif 4
 375 tunnel interface.
 376 .It Dv IPV6CTL_KAME_VERSION
 377 .Pq ip6.kame_version
 378 String: identifies the version of KAME
 379 .Tn IPv6
 380 stack implemented in the kernel.
 381 .It Dv IPV6CTL_USE_DEPRECATED
 382 .Pq ip6.use_deprecated
 383 Boolean: enable/disable use of deprecated address,
 384 specified in RFC2462 5.5.4.
 385 Defaults to on.
 386 .It Dv IPV6CTL_RR_PRUNE
 387 .Pq ip6.rr_prune
 388 Integer: default interval between
 389 .Tn IPv6
 390 router renumbering prefix babysitting, in seconds.
 391 .It Dv IPV6CTL_V6ONLY
 392 .Pq ip6.v6only
 393 Boolean: enable/disable the prohibited use of
 394 .Tn IPv4
 395 mapped address on
 396 .Dv AF_INET6
 397 sockets.
 398 Defaults to off.
 399 .It Dv IPV6CTL_RTEXPIRE
 400 .Pq ip6.rtexpire
 401 Integer: lifetime in seconds of protocol-cloned
 402 .Tn IP
 403 routes after the last reference drops (default one hour).
 404 .\"This value varies dynamically as described above.
 405 .It Dv IPV6CTL_RTMINEXPIRE
 406 .Pq ip6.rtminexpire
 407 Integer: minimum value of ip.rtexpire (default ten seconds).
 408 .\"This value has no effect on user modifications, but restricts the dynamic
 409 .\"adaptation described above.
 410 .It Dv IPV6CTL_RTMAXCACHE
 411 .Pq ip6.rtmaxcache
 412 Integer: trigger level of cached, unreferenced, protocol-cloned routes
 413 which initiates dynamic adaptation (default 128).
 414 .El
 415 .Ss Interaction between IPv4/v6 sockets
 416 The behavior of
 417 .Dv AF_INET6
 418 TCP/UDP socket is documented in RFC2553.
 419 Basically, it says this:
 420 .Bl -bullet -compact
 421 .It
 422 A specific bind on an
 423 .Dv AF_INET6
 424 socket
 425 .Xr ( bind 2
 426 with an address specified)
 427 should accept IPv6 traffic to that address only.
 428 .It
 429 If you perform a wildcard bind
 430 on an
 431 .Dv AF_INET6
 432 socket
 433 .Xr ( bind 2
 434 to IPv6 address
 435 .Li :: ) ,
 436 and there is no wildcard bind
 437 .Dv AF_INET
 438 socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
 439 should be routed to that
 440 .Dv AF_INET6
 441 socket.
 442 IPv4 traffic should be seen as if it came from an IPv6 address like
 443 .Li ::ffff:10.1.1.1 .
 444 This is called an IPv4 mapped address.
 445 .It
 446 If there are both a wildcard bind
 447 .Dv AF_INET
 448 socket and a wildcard bind
 449 .Dv AF_INET6
 450 socket on one TCP/UDP port, they should behave separately.
 451 IPv4 traffic should be routed to the
 452 .Dv AF_INET
 453 socket and IPv6 should be routed to the
 454 .Dv AF_INET6
 455 socket.
 456 .El
 457 .Pp
 458 However, RFC2553 does not define the ordering constraint between calls to
 459 .Xr bind 2 ,
 460 nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers
 461 relate to each other
 462 (should they be integrated or separated).
 463 Implemented behavior is very different from kernel to kernel.
 464 Therefore, it is unwise to rely too much upon the behavior of
 465 .Dv AF_INET6
 466 wildcard bind sockets.
 467 It is recommended to listen to two sockets, one for
 468 .Dv AF_INET
 469 and another for
 470 .Dv AF_INET6 ,
 471 when you would like to accept both IPv4 and IPv6 traffic.
 472 .Pp
 473 It should also be noted that
 474 malicious parties can take advantage of the complexity presented above,
 475 and are able to bypass access control,
 476 if the target node routes IPv4 traffic to
 477 .Dv AF_INET6
 478 socket.
 479 Users are advised to take care handling connections
 480 from IPv4 mapped address to
 481 .Dv AF_INET6
 482 sockets.
 483 .\".Pp
 484 .\"Because of the above, by default,
 485 .\"KAME/NetBSD and KAME/OpenBSD
 486 .\"does not route IPv4 traffic to
 487 .\".Dv AF_INET6
 488 .\"sockets.
 489 .\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
 490 .\"On KAME/NetBSD, IPv4 traffic may be routed with certain
 491 .\"per-socket/per-node configuration, however, it is not recommended.
 492 .\"Consult
 493 .\".Xr ip6 4
 494 .\"for details.
 495 .Sh SEE ALSO
 496 .Xr ioctl 2 ,
 497 .Xr socket 2 ,
 498 .Xr sysctl 3 ,
 499 .Xr icmp6 4 ,
 500 .Xr intro 4 ,
 501 .Xr ip6 4 ,
 502 .Xr tcp 4 ,
 503 .Xr ttcp 4 ,
 504 .Xr udp 4
 505 .Sh STANDARDS
 506 .Rs
 507 .%A Tatsuya Jinmei
 508 .%A Atsushi Onoe
 509 .%T "An Extension of Format for IPv6 Scoped Addresses"
 510 .%R internet draft
 511 .%D June 2000
 512 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 513 .%O work in progress material
 514 .Re
 515 .Sh HISTORY
 516 The
 517 .Nm
 518 protocol interfaces are defined in RFC2553 and RFC2292.
 519 The implementation described herein appeared in the WIDE/KAME project.
 520 .Sh BUGS
 521 The IPv6 support is subject to change as the Internet protocols develop.
 522 Users should not depend on details of the current implementation,
 523 but rather the services exported.
 524 .Pp
 525 Users are suggested to implement
 526 .Dq version independent
 527 code as much as possible, as you will need to support both
 528 .Xr inet 4
 529 and
 530 .Nm .