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