1.\" $KAME: ip6.4,v 1.23 2005/01/11 05:56:25 itojun Exp $ 2.\" $OpenBSD: ip6.4,v 1.21 2005/01/06 03:50:46 itojun Exp $ 3.\" $FreeBSD: src/share/man/man4/ip6.4,v 1.18 2005/01/23 16:02:48 gnn Exp $ 4.\" 5.\" Copyright (c) 1983, 1991, 1993 6.\" The Regents of the University of California. 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 University 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 REGENTS 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 REGENTS 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 May 20, 2018 33.Dt IP6 4 34.Os 35.Sh NAME 36.Nm ip6 37.Nd Internet Protocol version 6 (IPv6) network layer 38.Sh SYNOPSIS 39.In sys/socket.h 40.In netinet/in.h 41.Ft int 42.Fn socket AF_INET6 SOCK_RAW proto 43.Sh DESCRIPTION 44The IPv6 network layer is used by the IPv6 protocol family for 45transporting data. 46IPv6 packets contain an IPv6 header that is not provided as part of the 47payload contents when passed to an application. 48IPv6 header options affect the behavior of this protocol and may be used 49by high-level protocols (such as the 50.Xr tcp 4 51and 52.Xr udp 4 53protocols) as well as directly by 54.Dq raw sockets , 55which process IPv6 messages at a lower-level and may be useful for 56developing new protocols and special-purpose applications. 57.Ss Header 58All IPv6 packets begin with an IPv6 header. 59When data received by the kernel are passed to the application, this 60header is not included in buffer, even when raw sockets are being used. 61Likewise, when data are sent to the kernel for transmit from the 62application, the buffer is not examined for an IPv6 header: 63the kernel always constructs the header. 64To directly access IPv6 headers from received packets and specify them 65as part of the buffer passed to the kernel, link-level access 66.Po 67.Xr bpf 4 , 68for example 69.Pc 70must instead be utilized. 71.Pp 72The header has the following definition: 73.Bd -literal -offset indent 74struct ip6_hdr { 75 union { 76 struct ip6_hdrctl { 77 u_int32_t ip6_un1_flow; /* 20 bits of flow ID */ 78 u_int16_t ip6_un1_plen; /* payload length */ 79 u_int8_t ip6_un1_nxt; /* next header */ 80 u_int8_t ip6_un1_hlim; /* hop limit */ 81 } ip6_un1; 82 u_int8_t ip6_un2_vfc; /* version and class */ 83 } ip6_ctlun; 84 struct in6_addr ip6_src; /* source address */ 85 struct in6_addr ip6_dst; /* destination address */ 86} __packed; 87 88#define ip6_vfc ip6_ctlun.ip6_un2_vfc 89#define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow 90#define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen 91#define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt 92#define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim 93#define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim 94.Ed 95.Pp 96All fields are in network-byte order. 97Any options specified (see 98.Sx Options 99below) must also be specified in network-byte order. 100.Pp 101.Va ip6_flow 102specifies the flow ID. 103.Va ip6_plen 104specifies the payload length. 105.Va ip6_nxt 106specifies the type of the next header. 107.Va ip6_hlim 108specifies the hop limit. 109.Pp 110The top 4 bits of 111.Va ip6_vfc 112specify the class and the bottom 4 bits specify the version. 113.Pp 114.Va ip6_src 115and 116.Va ip6_dst 117specify the source and destination addresses. 118.Pp 119The IPv6 header may be followed by any number of extension headers that start 120with the following generic definition: 121.Bd -literal -offset indent 122struct ip6_ext { 123 u_int8_t ip6e_nxt; 124 u_int8_t ip6e_len; 125} __packed; 126.Ed 127.Ss Options 128IPv6 allows header options on packets to manipulate the behavior of the 129protocol. 130These options and other control requests are accessed with the 131.Xr getsockopt 2 132and 133.Xr setsockopt 2 134system calls at level 135.Dv IPPROTO_IPV6 136and by using ancillary data in 137.Xr recvmsg 2 138and 139.Xr sendmsg 2 . 140They can be used to access most of the fields in the IPv6 header and 141extension headers. 142.Pp 143The following socket options are supported: 144.Bl -tag -width Ds 145.\" .It Dv IPV6_OPTIONS 146.It Dv IPV6_UNICAST_HOPS Fa "int *" 147Get or set the default hop limit header field for outgoing unicast 148datagrams sent on this socket. 149A value of \-1 resets to the default value. 150.\" .It Dv IPV6_RECVOPTS Fa "int *" 151.\" Get or set the status of whether all header options will be 152.\" delivered along with the datagram when it is received. 153.\" .It Dv IPV6_RECVRETOPTS Fa "int *" 154.\" Get or set the status of whether header options will be delivered 155.\" for reply. 156.\" .It Dv IPV6_RECVDSTADDR Fa "int *" 157.\" Get or set the status of whether datagrams are received with 158.\" destination addresses. 159.\" .It Dv IPV6_RETOPTS 160.\" Get or set IPv6 options. 161.It Dv IPV6_MULTICAST_IF Fa "u_int *" 162Get or set the interface from which multicast packets will be sent. 163For hosts with multiple interfaces, each multicast transmission is sent 164from the primary network interface. 165The interface is specified as its index as provided by 166.Xr if_nametoindex 3 . 167A value of zero specifies the default interface. 168.It Dv IPV6_MULTICAST_HOPS Fa "int *" 169Get or set the default hop limit header field for outgoing multicast 170datagrams sent on this socket. 171This option controls the scope of multicast datagram transmissions. 172.Pp 173Datagrams with a hop limit of 1 are not forwarded beyond the local 174network. 175Multicast datagrams with a hop limit of zero will not be transmitted on 176any network but may be delivered locally if the sending host belongs to 177the destination group and if multicast loopback (see below) has not been 178disabled on the sending socket. 179Multicast datagrams with a hop limit greater than 1 may be forwarded to 180the other networks if a multicast router (such as 181.Xr mrouted 8 ) 182is attached to the local network. 183.It Dv IPV6_MULTICAST_LOOP Fa "u_int *" 184Get or set the status of whether multicast datagrams will be looped back 185for local delivery when a multicast datagram is sent to a group to which 186the sending host belongs. 187.Pp 188This option improves performance for applications that may have no more 189than one instance on a single host (such as a router daemon) by 190eliminating the overhead of receiving their own transmissions. 191It should generally not be used by applications for which there may be 192more than one instance on a single host (such as a conferencing program) 193or for which the sender does not belong to the destination group 194(such as a time-querying program). 195.Pp 196A multicast datagram sent with an initial hop limit greater than 1 may 197be delivered to the sending host on a different interface from that on 198which it was sent if the host belongs to the destination group on that 199other interface. 200The multicast loopback control option has no effect on such delivery. 201.It Dv IPV6_JOIN_GROUP Fa "struct ipv6_mreq *" 202Join a multicast group. 203A host must become a member of a multicast group before it can receive 204datagrams sent to the group. 205.Bd -literal 206struct ipv6_mreq { 207 struct in6_addr ipv6mr_multiaddr; 208 unsigned int ipv6mr_interface; 209}; 210.Ed 211.Pp 212.Va ipv6mr_interface 213may be set to zeroes to choose the default multicast interface or to the 214index of a particular multicast-capable interface if the host is 215multihomed. 216Membership is associated with a single interface; programs running on 217multihomed hosts may need to join the same group on more than one 218interface. 219.Pp 220If the multicast address is unspecified (i.e., all zeroes), messages 221from all multicast addresses will be accepted by this group. 222Note that setting to this value requires superuser privileges. 223.It Dv IPV6_LEAVE_GROUP Fa "struct ipv6_mreq *" 224Drop membership from the associated multicast group. 225Memberships are automatically dropped when the socket is closed or when 226the process exits. 227.It Dv IPV6_PORTRANGE Fa "int *" 228Get or set the allocation policy of ephemeral ports for when the kernel 229automatically binds a local address to this socket. 230The following values are available: 231.Pp 232.Bl -tag -width IPV6_PORTRANGE_DEFAULT -compact 233.It Dv IPV6_PORTRANGE_DEFAULT 234Use the regular range of non-reserved ports (varies, see 235.Xr sysctl 8 ) . 236.It Dv IPV6_PORTRANGE_HIGH 237Use a high range (varies, see 238.Xr sysctl 8 ) . 239.It Dv IPV6_PORTRANGE_LOW 240Use a low, reserved range (600\-1023). 241.El 242.It Dv IPV6_PKTINFO Fa "int *" 243Get or set whether additional information about subsequent packets will 244be provided as ancillary data along with the payload in subsequent 245.Xr recvmsg 2 246calls. 247The information is stored in the following structure in the ancillary 248data returned: 249.Bd -literal 250struct in6_pktinfo { 251 struct in6_addr ipi6_addr; /* src/dst IPv6 address */ 252 unsigned int ipi6_ifindex; /* send/recv if index */ 253}; 254.Ed 255.It Dv IPV6_HOPLIMIT Fa "int *" 256Get or set whether the hop limit header field from subsequent packets 257will be provided as ancillary data along with the payload in subsequent 258.Xr recvmsg 2 259calls. 260The value is stored as an 261.Vt int 262in the ancillary data returned. 263.\" .It Dv IPV6_NEXTHOP Fa "int *" 264.\" Get or set whether the address of the next hop for subsequent 265.\" packets will be provided as ancillary data along with the payload in 266.\" subsequent 267.\" .Xr recvmsg 2 268.\" calls. 269.\" The option is stored as a 270.\" .Vt sockaddr 271.\" structure in the ancillary data returned. 272.\" .Pp 273.\" This option requires superuser privileges. 274.It Dv IPV6_HOPOPTS Fa "int *" 275Get or set whether the hop-by-hop options from subsequent packets will be 276provided as ancillary data along with the payload in subsequent 277.Xr recvmsg 2 278calls. 279The option is stored in the following structure in the ancillary data 280returned: 281.Bd -literal 282struct ip6_hbh { 283 u_int8_t ip6h_nxt; /* next header */ 284 u_int8_t ip6h_len; /* length in units of 8 octets */ 285/* followed by options */ 286} __packed; 287.Ed 288.Pp 289The 290.Fn inet6_option_space 291routine and family of routines may be used to manipulate this data. 292.Pp 293This option requires superuser privileges. 294.It Dv IPV6_DSTOPTS Fa "int *" 295Get or set whether the destination options from subsequent packets will 296be provided as ancillary data along with the payload in subsequent 297.Xr recvmsg 2 298calls. 299The option is stored in the following structure in the ancillary data 300returned: 301.Bd -literal 302struct ip6_dest { 303 u_int8_t ip6d_nxt; /* next header */ 304 u_int8_t ip6d_len; /* length in units of 8 octets */ 305/* followed by options */ 306} __packed; 307.Ed 308.Pp 309The 310.Fn inet6_option_space 311routine and family of routines may be used to manipulate this data. 312.Pp 313This option requires superuser privileges. 314.It Dv IPV6_RTHDR Fa "int *" 315Get or set whether the routing header from subsequent packets will be 316provided as ancillary data along with the payload in subsequent 317.Xr recvmsg 2 318calls. 319The header is stored in the following structure in the ancillary data 320returned: 321.Bd -literal 322struct ip6_rthdr { 323 u_int8_t ip6r_nxt; /* next header */ 324 u_int8_t ip6r_len; /* length in units of 8 octets */ 325 u_int8_t ip6r_type; /* routing type */ 326 u_int8_t ip6r_segleft; /* segments left */ 327/* followed by routing-type-specific data */ 328} __packed; 329.Ed 330.Pp 331The 332.Fn inet6_option_space 333routine and family of routines may be used to manipulate this data. 334.Pp 335This option requires superuser privileges. 336.It Dv IPV6_PKTOPTIONS Fa "struct cmsghdr *" 337Get or set all header options and extension headers at one time on the 338last packet sent or received on the socket. 339All options must fit within the size of an mbuf (see 340.Xr mbuf 9 ) . 341Options are specified as a series of 342.Vt cmsghdr 343structures followed by corresponding values. 344.Va cmsg_level 345is set to 346.Dv IPPROTO_IPV6 , 347.Va cmsg_type 348to one of the other values in this list, and trailing data to the option 349value. 350When setting options, if the length 351.Va optlen 352to 353.Xr setsockopt 2 354is zero, all header options will be reset to their default values. 355Otherwise, the length should specify the size the series of control 356messages consumes. 357.Pp 358Instead of using 359.Xr sendmsg 2 360to specify option values, the ancillary data used in these calls that 361correspond to the desired header options may be directly specified as 362the control message in the series of control messages provided as the 363argument to 364.Xr setsockopt 2 . 365.It Dv IPV6_CHECKSUM Fa "int *" 366Get or set the byte offset into a packet where the 16-bit checksum is 367located. 368When set, this byte offset is where incoming packets will be expected 369to have checksums of their data stored and where outgoing packets will 370have checksums of their data computed and stored by the kernel. 371A value of \-1 specifies that no checksums will be checked on incoming 372packets and that no checksums will be computed or stored on outgoing 373packets. 374The offset of the checksum for ICMPv6 sockets cannot be relocated or 375turned off. 376.It Dv IPV6_V6ONLY Fa "int *" 377Get or set whether only IPv6 connections can be made to this socket. 378For wildcard sockets, this can restrict connections to IPv6 only. 379With 380.Dx , 381the socket option cannot be set to 0 (which will result in returning 382.Er EOPNOTSUPP ) . 383.It Dv IPV6_USE_MIN_MTU Fa "int *" 384Get or set whether the minimal IPv6 maximum transmission unit (MTU) size 385will be used to avoid fragmentation from occurring for subsequent 386outgoing datagrams. 387.El 388.Pp 389The 390.Dv IPV6_PKTINFO , 391.\" .Dv IPV6_NEXTHOP , 392.Dv IPV6_HOPLIMIT , 393.Dv IPV6_HOPOPTS , 394.Dv IPV6_DSTOPTS , 395and 396.Dv IPV6_RTHDR 397options will return ancillary data along with payload contents in subsequent 398.Xr recvmsg 2 399calls with 400.Va cmsg_level 401set to 402.Dv IPPROTO_IPV6 403and 404.Va cmsg_type 405set to respective option name value (e.g., 406.Dv IPV6_HOPLIMIT ) . 407These options may also be used directly as ancillary 408.Va cmsg_type 409values in 410.Xr sendmsg 2 411to set options on the packet being transmitted by the call. 412The 413.Va cmsg_level 414value must be 415.Dv IPPROTO_IPV6 . 416For these options, the ancillary data object value format is the same 417as the value returned as explained for each when received with 418.Xr recvmsg 2 . 419.Pp 420Note that using 421.Xr sendmsg 2 422to specify options on particular packets works only on UDP and raw sockets. 423To manipulate header options for packets on TCP sockets, only the socket 424options may be used. 425.Pp 426In some cases, there are multiple APIs defined for manipulating an IPv6 427header field. 428A good example is the outgoing interface for multicast datagrams, which 429can be set by the 430.Dv IPV6_MULTICAST_IF 431socket option, through the 432.Dv IPV6_PKTINFO 433option, and through the 434.Va sin6_scope_id 435field of the socket address passed to the 436.Xr sendto 2 437system call. 438.Pp 439Resolving these conflicts is implementation dependent. 440This implementation determines the value in the following way: 441options specified by using ancillary data (i.e., 442.Xr sendmsg 2 ) 443are considered first, 444options specified by using 445.Dv IPV6_PKTOPTIONS 446to set 447.Dq sticky 448options are considered second, 449options specified by using the individual, basic, and direct socket 450options (e.g., 451.Dv IPV6_UNICAST_HOPS ) 452are considered third, 453and options specified in the socket address supplied to 454.Xr sendto 2 455are the last choice. 456.Ss Multicasting 457IPv6 multicasting is supported only on 458.Dv AF_INET6 459sockets of type 460.Dv SOCK_DGRAM 461and 462.Dv SOCK_RAW , 463and only on networks where the interface driver supports 464multicasting. 465Socket options (see above) that manipulate membership of 466multicast groups and other multicast options include 467.Dv IPV6_MULTICAST_IF , 468.Dv IPV6_MULTICAST_HOPS , 469.Dv IPV6_MULTICAST_LOOP , 470.Dv IPV6_LEAVE_GROUP , 471and 472.Dv IPV6_JOIN_GROUP . 473.Ss Raw Sockets 474Raw IPv6 sockets are connectionless and are normally used with the 475.Xr sendto 2 476and 477.Xr recvfrom 2 478calls, although the 479.Xr connect 2 480call may be used to fix the destination address for future outgoing 481packets so that 482.Xr send 2 483may instead be used and the 484.Xr bind 2 485call may be used to fix the source address for future outgoing 486packets instead of having the kernel choose a source address. 487.Pp 488By using 489.Xr connect 2 490or 491.Xr bind 2 , 492raw socket input is constrained to only packets with their 493source address matching the socket destination address if 494.Xr connect 2 495was used and to packets with their destination address 496matching the socket source address if 497.Xr bind 2 498was used. 499.Pp 500If the 501.Ar proto 502argument to 503.Xr socket 2 504is zero, the default protocol 505.Pq Dv IPPROTO_RAW 506is used for outgoing packets. 507For incoming packets, protocols recognized by kernel are 508.Sy not 509passed to the application socket (e.g., 510.Xr tcp 4 511and 512.Xr udp 4 ) 513except for some ICMPv6 messages. 514The ICMPv6 messages not passed to raw sockets include echo, timestamp, 515and address mask requests. 516If 517.Ar proto 518is non-zero, only packets with this protocol will be passed to the 519socket. 520.Pp 521IPv6 fragments are also not passed to application sockets until 522they have been reassembled. 523If reception of all packets is desired, link-level access (such as 524.Xr bpf 4 ) 525must be used instead. 526.Pp 527Outgoing packets automatically have an IPv6 header prepended to them 528(based on the destination address and the protocol number the socket 529was created with). 530Incoming packets are received by an application without the IPv6 header 531or any extension headers. 532.Pp 533Outgoing packets will be fragmented automatically by the kernel if they 534are too large. 535Incoming packets will be reassembled before being sent to the raw socket, 536so packet fragments or fragment headers will never be seen on a raw socket. 537.Sh EXAMPLES 538The following determines the hop limit on the next packet received: 539.Bd -literal 540struct iovec iov[2]; 541u_char buf[BUFSIZ]; 542struct cmsghdr *cm; 543struct msghdr m; 544int found, optval; 545u_char data[2048]; 546 547/* Create socket. */ 548 549(void)memset(&m, 0, sizeof(m)); 550(void)memset(&iov, 0, sizeof(iov)); 551 552iov[0].iov_base = data; /* buffer for packet payload */ 553iov[0].iov_len = sizeof(data); /* expected packet length */ 554 555m.msg_name = &from; /* sockaddr_in6 of peer */ 556m.msg_namelen = sizeof(from); 557m.msg_iov = iov; 558m.msg_iovlen = 1; 559m.msg_control = (caddr_t)buf; /* buffer for control messages */ 560m.msg_controllen = sizeof(buf); 561 562/* 563 * Enable the hop limit value from received packets to be 564 * returned along with the payload. 565 */ 566optval = 1; 567if (setsockopt(s, IPPROTO_IPV6, IPV6_HOPLIMIT, &optval, 568 sizeof(optval)) == -1) 569 err(1, "setsockopt"); 570 571found = 0; 572while (!found) { 573 if (recvmsg(s, &m, 0) == -1) 574 err(1, "recvmsg"); 575 for (cm = CMSG_FIRSTHDR(&m); cm != NULL; 576 cm = CMSG_NXTHDR(&m, cm)) { 577 if (cm->cmsg_level == IPPROTO_IPV6 && 578 cm->cmsg_type == IPV6_HOPLIMIT && 579 cm->cmsg_len == CMSG_LEN(sizeof(int))) { 580 found = 1; 581 (void)printf("hop limit: %d\en", 582 *(int *)CMSG_DATA(cm)); 583 break; 584 } 585 } 586} 587.Ed 588.Sh DIAGNOSTICS 589A socket operation may fail with one of the following errors returned: 590.Bl -tag -width EADDRNOTAVAILxx 591.It Bq Er EISCONN 592when trying to establish a connection on a socket which 593already has one or when trying to send a datagram with the destination 594address specified and the socket is already connected. 595.It Bq Er ENOTCONN 596when trying to send a datagram, but 597no destination address is specified, and the socket hasn't been 598connected. 599.It Bq Er ENOBUFS 600when the system runs out of memory for 601an internal data structure. 602.It Bq Er EADDRNOTAVAIL 603when an attempt is made to create a 604socket with a network address for which no network interface 605exists. 606.It Bq Er EACCES 607when an attempt is made to create 608a raw IPv6 socket by a non-privileged process. 609.El 610.Pp 611The following errors specific to IPv6 may occur when setting or getting 612header options: 613.Bl -tag -width EADDRNOTAVAILxx 614.It Bq Er EINVAL 615An unknown socket option name was given. 616.It Bq Er EINVAL 617An ancillary data object was improperly formed. 618.El 619.Sh SEE ALSO 620.Xr getsockopt 2 , 621.Xr recv 2 , 622.Xr send 2 , 623.Xr setsockopt 2 , 624.Xr socket 2 , 625.\" .Xr inet6_option_space 3 , 626.\" .Xr inet6_rthdr_space 3 , 627.Xr if_nametoindex 3 , 628.Xr bpf 4 , 629.Xr icmp6 4 , 630.Xr inet6 4 , 631.Xr netintro 4 , 632.Xr tcp 4 , 633.Xr udp 4 634.Rs 635.%A W. Stevens 636.%A M. Thomas 637.%T Advanced Sockets API for IPv6 638.%R RFC 2292 639.%D February 1998 640.Re 641.Rs 642.%A S. Deering 643.%A R. Hinden 644.%T Internet Protocol, Version 6 (IPv6) Specification 645.%R RFC 2460 646.%D December 1998 647.Re 648.Rs 649.%A R. Gilligan 650.%A S. Thomson 651.%A J. Bound 652.%A W. Stevens 653.%T Basic Socket Interface Extensions for IPv6 654.%R RFC 2553 655.%D March 1999 656.Re 657.Rs 658.%A W. Stevens 659.%A B. Fenner 660.%A A. Rudoff 661.%T UNIX Network Programming, third edition 662.Re 663.Sh STANDARDS 664Most of the socket options are defined in RFC 2292 or RFC 2553. 665The 666.Dv IPV6_V6ONLY 667socket option is defined in RFC 3542. 668The 669.Dv IPV6_PORTRANGE 670socket option and the conflict resolution rule are not defined in the 671RFCs and should be considered implementation dependent. 672