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