share/man/man4/inet6.4

   1 .\"     $KAME: inet6.4,v 1.21 2001/04/05 01:00:18 itojun Exp $
   2 .\"
   3 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the project nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd August 14, 2018
  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 .In 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         uint8_t         sin6_len;
  82         sa_family_t     sin6_family;
  83         in_port_t       sin6_port;
  84         uint32_t        sin6_flowinfo;
  85         struct in6_addr sin6_addr;
  86         uint32_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 .Ss MIB Variables
 188 A number of variables are implemented in the net.inet6 branch of the
 189 .Xr sysctl 3
 190 MIB.
 191 In addition to the variables supported by the transport protocols
 192 (for which the respective manual pages may be consulted),
 193 the following general variables are defined:
 194 .Bl -tag -width IPV6CTL_MAXFRAGPACKETS
 195 .It Dv IPV6CTL_FORWARDING
 196 .Pq ip6.forwarding
 197 Boolean: enable/disable forwarding of
 198 .Tn IPv6
 199 packets.
 200 Also, identify if the node is acting as a router.
 201 Defaults to off.
 202 .It Dv IPV6CTL_SENDREDIRECTS
 203 .Pq ip6.redirect
 204 Boolean: enable/disable sending of
 205 .Tn ICMPv6
 206 redirects in response to unforwardable
 207 .Tn IPv6
 208 packets.
 209 This option is ignored unless the node is routing
 210 .Tn IPv6
 211 packets,
 212 and should normally be enabled on all systems.
 213 Defaults to on.
 214 .It Dv IPV6CTL_DEFHLIM
 215 .Pq ip6.hlim
 216 Integer: default hop limit value to use for outgoing
 217 .Tn IPv6
 218 packets.
 219 This value applies to all the transport protocols on top of
 220 .Tn IPv6 .
 221 There are APIs to override the value.
 222 .It Dv IPV6CTL_MAXFRAGS
 223 .Pq ip6.maxfrags
 224 Integer: maximum number of fragments the host will accept and simultaneously
 225 hold across all reassembly queues in all VNETs.
 226 If set to 0, fragment reassembly is disabled.
 227 If set to -1, this limit is not applied.
 228 This limit is recalculated when the number of mbuf clusters is changed.
 229 This is a global limit.
 230 .It Dv IPV6CTL_MAXFRAGPACKETS
 231 .Pq ip6.maxfragpackets
 232 Integer: maximum number of fragmented packets the node will accept and
 233 simultaneously hold in the reassembly queue for a particular VNET.
 234 0 means that the node will not accept any fragmented packets for that VNET.
 235 -1 means that the node will not apply this limit for that VNET.
 236 This limit is recalculated when the number of mbuf clusters is changed.
 237 This is a per-VNET limit.
 238 .It Dv IPV6CTL_MAXFRAGBUCKETSIZE
 239 .Pq ip6.maxfragbucketsize
 240 Integer: maximum number of reassembly queues per bucket.
 241 Fragmented packets are hashed to buckets.
 242 Each bucket has a list of reassembly queues.
 243 The system must compare the incoming packets to the existing reassembly queues
 244 in the bucket to find a matching reassembly queue.
 245 To preserve system resources, the system limits the number of reassembly
 246 queues allowed in each bucket.
 247 This limit is recalculated when the number of mbuf clusters is changed or
 248 when the value of
 249 .Va ip6.maxfragpackets
 250 changes.
 251 This is a per-VNET limit.
 252 .It Dv IPV6CTL_MAXFRAGSPERPACKET
 253 .Pq ip6.maxfragsperpacket
 254 Integer: maximum number of fragments the host will accept and hold in the
 255 ressembly queue for a packet.
 256 This is a per-VNET limit.
 257 .It Dv IPV6CTL_ACCEPT_RTADV
 258 .Pq ip6.accept_rtadv
 259 Boolean: the default value of a per-interface flag to
 260 enable/disable receiving of
 261 .Tn ICMPv6
 262 router advertisement packets,
 263 and autoconfiguration of address prefixes and default routers.
 264 The node must be a host
 265 (not a router)
 266 for the option to be meaningful.
 267 Defaults to off.
 268 .It Dv IPV6CTL_AUTO_LINKLOCAL
 269 .Pq ip6.auto_linklocal
 270 Boolean: the default value of a per-interface flag to
 271 enable/disable performing automatic link-local address configuration.
 272 Defaults to on.
 273 .It Dv IPV6CTL_LOG_INTERVAL
 274 .Pq ip6.log_interval
 275 Integer: default interval between
 276 .Tn IPv6
 277 packet forwarding engine log output
 278 (in seconds).
 279 .It Dv IPV6CTL_HDRNESTLIMIT
 280 .Pq ip6.hdrnestlimit
 281 Integer: default number of the maximum
 282 .Tn IPv6
 283 extension headers
 284 permitted on incoming
 285 .Tn IPv6
 286 packets.
 287 If set to 0, the node will accept as many extension headers as possible.
 288 .It Dv IPV6CTL_DAD_COUNT
 289 .Pq ip6.dad_count
 290 Integer: default number of
 291 .Tn IPv6
 292 DAD
 293 .Pq duplicated address detection
 294 probe packets.
 295 The packets will be generated when
 296 .Tn IPv6
 297 interface addresses are configured.
 298 .It Dv IPV6CTL_AUTO_FLOWLABEL
 299 .Pq ip6.auto_flowlabel
 300 Boolean: enable/disable automatic filling of
 301 .Tn IPv6
 302 flowlabel field, for outstanding connected transport protocol packets.
 303 The field might be used by intermediate routers to identify packet flows.
 304 Defaults to on.
 305 .It Dv IPV6CTL_DEFMCASTHLIM
 306 .Pq ip6.defmcasthlim
 307 Integer: default hop limit value for an
 308 .Tn IPv6
 309 multicast packet sourced by the node.
 310 This value applies to all the transport protocols on top of
 311 .Tn IPv6 .
 312 There are APIs to override the value as documented in
 313 .Xr ip6 4 .
 314 .It Dv IPV6CTL_GIF_HLIM
 315 .Pq ip6.gifhlim
 316 Integer: default maximum hop limit value for an
 317 .Tn IPv6
 318 packet generated by
 319 .Xr gif 4
 320 tunnel interface.
 321 .It Dv IPV6CTL_KAME_VERSION
 322 .Pq ip6.kame_version
 323 String: identifies the version of KAME
 324 .Tn IPv6
 325 stack implemented in the kernel.
 326 .It Dv IPV6CTL_USE_DEPRECATED
 327 .Pq ip6.use_deprecated
 328 Boolean: enable/disable use of deprecated address,
 329 specified in RFC2462 5.5.4.
 330 Defaults to on.
 331 .It Dv IPV6CTL_RR_PRUNE
 332 .Pq ip6.rr_prune
 333 Integer: default interval between
 334 .Tn IPv6
 335 router renumbering prefix babysitting, in seconds.
 336 .It Dv IPV6CTL_V6ONLY
 337 .Pq ip6.v6only
 338 Boolean: enable/disable the prohibited use of
 339 .Tn IPv4
 340 mapped address on
 341 .Dv AF_INET6
 342 sockets.
 343 Defaults to on.
 344 .El
 345 .Ss Interaction between IPv4/v6 sockets
 346 By default,
 347 .Fx
 348 does not route IPv4 traffic to
 349 .Dv AF_INET6
 350 sockets.
 351 The default behavior intentionally violates RFC2553 for security reasons.
 352 Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
 353 IPv4 traffic may be routed with certain
 354 per-socket/per-node configuration, however, it is not recommended to do so.
 355 Consult
 356 .Xr ip6 4
 357 for details.
 358 .Pp
 359 The behavior of
 360 .Dv AF_INET6
 361 TCP/UDP socket is documented in RFC2553.
 362 Basically, it says this:
 363 .Bl -bullet -compact
 364 .It
 365 A specific bind on an
 366 .Dv AF_INET6
 367 socket
 368 .Xr ( bind 2
 369 with an address specified)
 370 should accept IPv6 traffic to that address only.
 371 .It
 372 If you perform a wildcard bind
 373 on an
 374 .Dv AF_INET6
 375 socket
 376 .Xr ( bind 2
 377 to IPv6 address
 378 .Li :: ) ,
 379 and there is no wildcard bind
 380 .Dv AF_INET
 381 socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
 382 should be routed to that
 383 .Dv AF_INET6
 384 socket.
 385 IPv4 traffic should be seen as if it came from an IPv6 address like
 386 .Li ::ffff:10.1.1.1 .
 387 This is called an IPv4 mapped address.
 388 .It
 389 If there are both a wildcard bind
 390 .Dv AF_INET
 391 socket and a wildcard bind
 392 .Dv AF_INET6
 393 socket on one TCP/UDP port, they should behave separately.
 394 IPv4 traffic should be routed to the
 395 .Dv AF_INET
 396 socket and IPv6 should be routed to the
 397 .Dv AF_INET6
 398 socket.
 399 .El
 400 .Pp
 401 However, RFC2553 does not define the ordering constraint between calls to
 402 .Xr bind 2 ,
 403 nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers
 404 relate to each other
 405 (should they be integrated or separated).
 406 Implemented behavior is very different from kernel to kernel.
 407 Therefore, it is unwise to rely too much upon the behavior of
 408 .Dv AF_INET6
 409 wildcard bind sockets.
 410 It is recommended to listen to two sockets, one for
 411 .Dv AF_INET
 412 and another for
 413 .Dv AF_INET6 ,
 414 when you would like to accept both IPv4 and IPv6 traffic.
 415 .Pp
 416 It should also be noted that
 417 malicious parties can take advantage of the complexity presented above,
 418 and are able to bypass access control,
 419 if the target node routes IPv4 traffic to
 420 .Dv AF_INET6
 421 socket.
 422 Users are advised to take care handling connections
 423 from IPv4 mapped address to
 424 .Dv AF_INET6
 425 sockets.
 426 .Sh SEE ALSO
 427 .Xr ioctl 2 ,
 428 .Xr socket 2 ,
 429 .Xr sysctl 3 ,
 430 .Xr icmp6 4 ,
 431 .Xr intro 4 ,
 432 .Xr ip6 4 ,
 433 .Xr tcp 4 ,
 434 .Xr udp 4
 435 .Sh STANDARDS
 436 .Rs
 437 .%A Tatsuya Jinmei
 438 .%A Atsushi Onoe
 439 .%T "An Extension of Format for IPv6 Scoped Addresses"
 440 .%R internet draft
 441 .%D June 2000
 442 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 443 .%O work in progress material
 444 .Re
 445 .Sh HISTORY
 446 The
 447 .Nm
 448 protocol interfaces are defined in RFC2553 and RFC2292.
 449 The implementation described herein appeared in the WIDE/KAME project.
 450 .Sh BUGS
 451 The IPv6 support is subject to change as the Internet protocols develop.
 452 Users should not depend on details of the current implementation,
 453 but rather the services exported.
 454 .Pp
 455 Users are suggested to implement
 456 .Dq version independent
 457 code as much as possible, as you will need to support both
 458 .Xr inet 4
 459 and
 460 .Nm .