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 November 25, 2017
  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 .In 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         sa_family_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 RFC 2292.
 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 \(34, 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_LOG_INTERVAL
 318 .Pq ip6.log_interval
 319 Integer: default interval between
 320 .Tn IPv6
 321 packet forwarding engine log output
 322 (in seconds).
 323 .It Dv IPV6CTL_HDRNESTLIMIT
 324 .Pq ip6.hdrnestlimit
 325 Integer: default number of the maximum
 326 .Tn IPv6
 327 extension headers
 328 permitted on incoming
 329 .Tn IPv6
 330 packets.
 331 If set to 0, the node will accept as many extension headers as possible.
 332 .It Dv IPV6CTL_DAD_COUNT
 333 .Pq ip6.dad_count
 334 Integer: default number of
 335 .Tn IPv6
 336 DAD
 337 .Pq duplicated address detection
 338 probe packets.
 339 The packets will be generated when
 340 .Tn IPv6
 341 interface addresses are configured.
 342 .It Dv IPV6CTL_AUTO_FLOWLABEL
 343 .Pq ip6.auto_flowlabel
 344 Boolean: enable/disable automatic filling of
 345 .Tn IPv6
 346 flowlabel field, for outstanding connected transport protocol packets.
 347 The field might be used by intermediate routers to identify packet flows.
 348 Defaults to on.
 349 .It Dv IPV6CTL_DEFMCASTHLIM
 350 .Pq ip6.defmcasthlim
 351 Integer: default hop limit value for an
 352 .Tn IPv6
 353 multicast packet sourced by the node.
 354 This value applies to all the transport protocols on top of
 355 .Tn IPv6 .
 356 There are APIs to override the value as documented in
 357 .Xr ip6 4 .
 358 .It Dv IPV6CTL_GIF_HLIM
 359 .Pq ip6.gifhlim
 360 Integer: default maximum hop limit value for an
 361 .Tn IPv6
 362 packet generated by
 363 .Xr gif 4
 364 tunnel interface.
 365 .It Dv IPV6CTL_KAME_VERSION
 366 .Pq ip6.kame_version
 367 String: identifies the version of KAME
 368 .Tn IPv6
 369 stack implemented in the kernel.
 370 .It Dv IPV6CTL_USE_DEPRECATED
 371 .Pq ip6.use_deprecated
 372 Boolean: enable/disable use of deprecated address,
 373 specified in RFC 2462 5.5.4.
 374 Defaults to on.
 375 .It Dv IPV6CTL_RR_PRUNE
 376 .Pq ip6.rr_prune
 377 Integer: default interval between
 378 .Tn IPv6
 379 router renumbering prefix babysitting, in seconds.
 380 .It Dv IPV6CTL_RTEXPIRE
 381 .Pq ip6.rtexpire
 382 Integer: lifetime in seconds of protocol-cloned
 383 .Tn IP
 384 routes after the last reference drops (default one hour).
 385 .\"This value varies dynamically as described above.
 386 .It Dv IPV6CTL_RTMINEXPIRE
 387 .Pq ip6.rtminexpire
 388 Integer: minimum value of ip.rtexpire (default ten seconds).
 389 .\"This value has no effect on user modifications, but restricts the dynamic
 390 .\"adaptation described above.
 391 .It Dv IPV6CTL_RTMAXCACHE
 392 .Pq ip6.rtmaxcache
 393 Integer: trigger level of cached, unreferenced, protocol-cloned routes
 394 which initiates dynamic adaptation (default 128).
 395 .El
 396 .Ss Interaction between IPv4/v6 sockets
 397 The behavior of
 398 .Dv AF_INET6
 399 TCP/UDP socket is documented in RFC 2553.
 400 Basically, it says this:
 401 .Bl -bullet -compact
 402 .It
 403 A specific bind on an
 404 .Dv AF_INET6
 405 socket
 406 .Xr ( bind 2
 407 with an address specified)
 408 should accept IPv6 traffic to that address only.
 409 .It
 410 If you perform a wildcard bind
 411 on an
 412 .Dv AF_INET6
 413 socket
 414 .Xr ( bind 2
 415 to IPv6 address
 416 .Li :: ) ,
 417 and there is no wildcard bind
 418 .Dv AF_INET
 419 socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
 420 should be routed to that
 421 .Dv AF_INET6
 422 socket.
 423 IPv4 traffic should be seen as if it came from an IPv6 address like
 424 .Li ::ffff:10.1.1.1 .
 425 This is called an IPv4 mapped address.
 426 .It
 427 If there are both a wildcard bind
 428 .Dv AF_INET
 429 socket and a wildcard bind
 430 .Dv AF_INET6
 431 socket on one TCP/UDP port, they should behave separately.
 432 IPv4 traffic should be routed to the
 433 .Dv AF_INET
 434 socket and IPv6 should be routed to the
 435 .Dv AF_INET6
 436 socket.
 437 .El
 438 .Pp
 439 However, RFC 2553 does not define the ordering constraint between calls to
 440 .Xr bind 2 ,
 441 nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers
 442 relate to each other
 443 (should they be integrated or separated).
 444 Implemented behavior is very different from kernel to kernel.
 445 Therefore, it is unwise to rely too much upon the behavior of
 446 .Dv AF_INET6
 447 wildcard bind sockets.
 448 It is recommended to listen to two sockets, one for
 449 .Dv AF_INET
 450 and another for
 451 .Dv AF_INET6 ,
 452 when you would like to accept both IPv4 and IPv6 traffic.
 453 .Pp
 454 It should also be noted that
 455 malicious parties can take advantage of the complexity presented above,
 456 and are able to bypass access control,
 457 if the target node routes IPv4 traffic to
 458 .Dv AF_INET6
 459 socket.
 460 Users are advised to take care handling connections
 461 from IPv4 mapped address to
 462 .Dv AF_INET6
 463 sockets.
 464 .\".Pp
 465 .\"Because of the above, by default,
 466 .\"KAME/NetBSD and KAME/OpenBSD
 467 .\"does not route IPv4 traffic to
 468 .\".Dv AF_INET6
 469 .\"sockets.
 470 .\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
 471 .\"On KAME/NetBSD, IPv4 traffic may be routed with certain
 472 .\"per-socket/per-node configuration, however, it is not recommended.
 473 .\"Consult
 474 .\".Xr ip6 4
 475 .\"for details.
 476 .Sh SEE ALSO
 477 .Xr ioctl 2 ,
 478 .Xr socket 2 ,
 479 .Xr sysctl 3 ,
 480 .Xr icmp6 4 ,
 481 .Xr intro 4 ,
 482 .Xr ip6 4 ,
 483 .Xr tcp 4 ,
 484 .Xr udp 4
 485 .Sh STANDARDS
 486 .Rs
 487 .%A Tatsuya Jinmei
 488 .%A Atsushi Onoe
 489 .%T "An Extension of Format for IPv6 Scoped Addresses"
 490 .%R internet draft
 491 .%D June 2000
 492 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 493 .%O work in progress material
 494 .Re
 495 .Sh HISTORY
 496 The
 497 .Nm
 498 protocol interfaces are defined in RFC 2553 and RFC 2292.
 499 The implementation described herein appeared in the WIDE/KAME project.
 500 .Sh BUGS
 501 The IPv6 support is subject to change as the Internet protocols develop.
 502 Users should not depend on details of the current implementation,
 503 but rather the services exported.
 504 .Pp
 505 Users are suggested to implement
 506 .Dq version independent
 507 code as much as possible, as you will need to support both
 508 .Xr inet 4
 509 and
 510 .Nm .