| 1 |
.\" SPDX-License-Identifier: Linux-man-pages-1-para |
| 2 |
.\" |
| 3 |
.\" This man page is Copyright (C) 2000 Andi Kleen <[email protected]>. |
| 4 |
.\" |
| 5 |
.\" $Id: ipv6.7,v 1.3 2000/12/20 18:10:31 ak Exp $ |
| 6 |
.\" |
| 7 |
.\" The following socket options are undocumented |
| 8 |
.\" All of the following are from: |
| 9 |
.\" commit 333fad5364d6b457c8d837f7d05802d2aaf8a961 |
| 10 |
.\" Author: YOSHIFUJI Hideaki <[email protected]> |
| 11 |
.\" Support several new sockopt / ancillary data in Advanced API (RFC3542). |
| 12 |
.\" IPV6_2292PKTINFO (2.6.14) |
| 13 |
.\" Formerly IPV6_PKTINFO |
| 14 |
.\" IPV6_2292HOPOPTS (2.6.14) |
| 15 |
.\" Formerly IPV6_HOPOPTS, which is documented |
| 16 |
.\" IPV6_2292DSTOPTS (2.6.14) |
| 17 |
.\" Formerly IPV6_DSTOPTS, which is documented |
| 18 |
.\" IPV6_2292RTHDR (2.6.14) |
| 19 |
.\" Formerly IPV6_RTHDR, which is documented |
| 20 |
.\" IPV6_2292PKTOPTIONS (2.6.14) |
| 21 |
.\" Formerly IPV6_PKTOPTIONS |
| 22 |
.\" IPV6_2292HOPLIMIT (2.6.14) |
| 23 |
.\" Formerly IPV6_HOPLIMIT, which is documented |
| 24 |
.\" |
| 25 |
.\" IPV6_RECVHOPLIMIT (2.6.14) |
| 26 |
.\" IPV6_RECVHOPOPTS (2.6.14) |
| 27 |
.\" IPV6_RTHDRDSTOPTS (2.6.14) |
| 28 |
.\" IPV6_RECVRTHDR (2.6.14) |
| 29 |
.\" IPV6_RECVDSTOPTS (2.6.14) |
| 30 |
.\" |
| 31 |
.\" IPV6_RECVPATHMTU (Linux 2.6.35, flag value added in Linux 2.6.14) |
| 32 |
.\" commit 793b14731686595a741d9f47726ad8b9a235385a |
| 33 |
.\" Author: Brian Haley <[email protected]> |
| 34 |
.\" IPV6_PATHMTU (Linux 2.6.35, flag value added in Linux 2.6.14) |
| 35 |
.\" commit 793b14731686595a741d9f47726ad8b9a235385a |
| 36 |
.\" Author: Brian Haley <[email protected]> |
| 37 |
.\" IPV6_DONTFRAG (Linux 2.6.35, flag value added in Linux 2.6.14) |
| 38 |
.\" commit 793b14731686595a741d9f47726ad8b9a235385a |
| 39 |
.\" Author: Brian Haley <[email protected]> |
| 40 |
.\" commit 4b340ae20d0e2366792abe70f46629e576adaf5e |
| 41 |
.\" Author: Brian Haley <[email protected]> |
| 42 |
.\" |
| 43 |
.\" IPV6_RECVTCLASS (Linux 2.6.14) |
| 44 |
.\" commit 41a1f8ea4fbfcdc4232f023732584aae2220de31 |
| 45 |
.\" Author: YOSHIFUJI Hideaki <[email protected]> |
| 46 |
.\" Based on patch from David L Stevens <[email protected]> |
| 47 |
.\" |
| 48 |
.\" IPV6_CHECKSUM (Linux 2.2) |
| 49 |
.\" IPV6_NEXTHOP (Linux 2.2) |
| 50 |
.\" IPV6_JOIN_ANYCAST (Linux 2.4.21 / Linux 2.6) |
| 51 |
.\" IPV6_LEAVE_ANYCAST (Linux 2.4.21 / Linux 2.6) |
| 52 |
.\" IPV6_FLOWLABEL_MGR (Linux 2.2.7 / Linux 2.4) |
| 53 |
.\" IPV6_FLOWINFO_SEND (Linux 2.2.7 / Linux 2.4) |
| 54 |
.\" IPV6_IPSEC_POLICY (Linux 2.6) |
| 55 |
.\" IPV6_XFRM_POLICY (Linux 2.6) |
| 56 |
.\" IPV6_TCLASS (Linux 2.6) |
| 57 |
.\" |
| 58 |
.\" IPV6_ADDR_PREFERENCES (Linux 2.6.26) |
| 59 |
.\" commit 7cbca67c073263c179f605bdbbdc565ab29d801d |
| 60 |
.\" Author: YOSHIFUJI Hideaki <[email protected]> |
| 61 |
.\" IPV6_MINHOPCOUNT (Linux 2.6.35) |
| 62 |
.\" commit e802af9cabb011f09b9c19a82faef3dd315f27eb |
| 63 |
.\" Author: Stephen Hemminger <[email protected]> |
| 64 |
.\" IPV6_ORIGDSTADDR (Linux 2.6.37) |
| 65 |
.\" Actually a CMSG rather than a sockopt? |
| 66 |
.\" In header file, we have IPV6_RECVORIGDSTADDR == IPV6_ORIGDSTADDR |
| 67 |
.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 |
| 68 |
.\" Author: Balazs Scheidler <[email protected]> |
| 69 |
.\" IPV6_RECVORIGDSTADDR (Linux 2.6.37) |
| 70 |
.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 |
| 71 |
.\" Author: Balazs Scheidler <[email protected]> |
| 72 |
.\" Support for IPV6_RECVORIGDSTADDR sockopt for UDP sockets |
| 73 |
.\" were contributed by Harry Mason. |
| 74 |
.\" IPV6_TRANSPARENT (Linux 2.6.37) |
| 75 |
.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 |
| 76 |
.\" Author: Balazs Scheidler <[email protected]> |
| 77 |
.\" IPV6_UNICAST_IF (Linux 3.4) |
| 78 |
.\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f |
| 79 |
.\" Author: Erich E. Hoover <[email protected]> |
| 80 |
.\" |
| 81 |
.TH ipv6 7 2024-05-02 "Linux man-pages 6.9.1" |
| 82 |
.SH NAME |
| 83 |
ipv6 \- Linux IPv6 protocol implementation |
| 84 |
.SH SYNOPSIS |
| 85 |
.nf |
| 86 |
.B #include <sys/socket.h> |
| 87 |
.B #include <netinet/in.h> |
| 88 |
.P |
| 89 |
.IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" |
| 90 |
.IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" |
| 91 |
.IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" |
| 92 |
.fi |
| 93 |
.SH DESCRIPTION |
| 94 |
Linux 2.2 optionally implements the Internet Protocol, version 6. |
| 95 |
This man page contains a description of the IPv6 basic API as |
| 96 |
implemented by the Linux kernel and glibc 2.1. |
| 97 |
The interface |
| 98 |
is based on the BSD sockets interface; see |
| 99 |
.BR socket (7). |
| 100 |
.P |
| 101 |
The IPv6 API aims to be mostly compatible with the |
| 102 |
IPv4 API (see |
| 103 |
.BR ip (7)). |
| 104 |
Only differences are described in this man page. |
| 105 |
.P |
| 106 |
To bind an |
| 107 |
.B AF_INET6 |
| 108 |
socket to any process, the local address should be copied from the |
| 109 |
.I in6addr_any |
| 110 |
variable which has |
| 111 |
.I in6_addr |
| 112 |
type. |
| 113 |
In static initializations, |
| 114 |
.B IN6ADDR_ANY_INIT |
| 115 |
may also be used, which expands to a constant expression. |
| 116 |
Both of them are in network byte order. |
| 117 |
.P |
| 118 |
The IPv6 loopback address (::1) is available in the global |
| 119 |
.I in6addr_loopback |
| 120 |
variable. |
| 121 |
For initializations, |
| 122 |
.B IN6ADDR_LOOPBACK_INIT |
| 123 |
should be used. |
| 124 |
.P |
| 125 |
IPv4 connections can be handled with the v6 API by using the |
| 126 |
v4-mapped-on-v6 address type; |
| 127 |
thus a program needs to support only this API type to |
| 128 |
support both protocols. |
| 129 |
This is handled transparently by the address |
| 130 |
handling functions in the C library. |
| 131 |
.P |
| 132 |
IPv4 and IPv6 share the local port space. |
| 133 |
When you get an IPv4 connection |
| 134 |
or packet to an IPv6 socket, |
| 135 |
its source address will be mapped to v6. |
| 136 |
.SS Address format |
| 137 |
.in +4n |
| 138 |
.EX |
| 139 |
struct sockaddr_in6 { |
| 140 |
sa_family_t sin6_family; /* AF_INET6 */ |
| 141 |
in_port_t sin6_port; /* port number */ |
| 142 |
uint32_t sin6_flowinfo; /* IPv6 flow information */ |
| 143 |
struct in6_addr sin6_addr; /* IPv6 address */ |
| 144 |
uint32_t sin6_scope_id; /* Scope ID (new in Linux 2.4) */ |
| 145 |
}; |
| 146 |
\& |
| 147 |
struct in6_addr { |
| 148 |
unsigned char s6_addr[16]; /* IPv6 address */ |
| 149 |
}; |
| 150 |
.EE |
| 151 |
.in |
| 152 |
.P |
| 153 |
.I sin6_family |
| 154 |
is always set to |
| 155 |
.BR AF_INET6 ; |
| 156 |
.I sin6_port |
| 157 |
is the protocol port (see |
| 158 |
.I sin_port |
| 159 |
in |
| 160 |
.BR ip (7)); |
| 161 |
.I sin6_flowinfo |
| 162 |
is the IPv6 flow identifier; |
| 163 |
.I sin6_addr |
| 164 |
is the 128-bit IPv6 address. |
| 165 |
.I sin6_scope_id |
| 166 |
is an ID depending on the scope of the address. |
| 167 |
It is new in Linux 2.4. |
| 168 |
Linux supports it only for link-local addresses, in that case |
| 169 |
.I sin6_scope_id |
| 170 |
contains the interface index (see |
| 171 |
.BR netdevice (7)) |
| 172 |
.P |
| 173 |
IPv6 supports several address types: unicast to address a single |
| 174 |
host, multicast to address a group of hosts, |
| 175 |
anycast to address the nearest member of a group of hosts |
| 176 |
(not implemented in Linux), IPv4-on-IPv6 to |
| 177 |
address an IPv4 host, and other reserved address types. |
| 178 |
.P |
| 179 |
The address notation for IPv6 is a group of 8 4-digit hexadecimal |
| 180 |
numbers, separated with a \[aq]:\[aq]. |
| 181 |
\&"::" stands for a string of 0 bits. |
| 182 |
Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> |
| 183 |
for IPv4-mapped-on-IPv6. |
| 184 |
.P |
| 185 |
The port space of IPv6 is shared with IPv4. |
| 186 |
.SS Socket options |
| 187 |
IPv6 supports some protocol-specific socket options that can be set with |
| 188 |
.BR setsockopt (2) |
| 189 |
and read with |
| 190 |
.BR getsockopt (2). |
| 191 |
The socket option level for IPv6 is |
| 192 |
.BR IPPROTO_IPV6 . |
| 193 |
A boolean integer flag is zero when it is false, otherwise true. |
| 194 |
.TP |
| 195 |
.B IPV6_ADDRFORM |
| 196 |
Turn an |
| 197 |
.B AF_INET6 |
| 198 |
socket into a socket of a different address family. |
| 199 |
Only |
| 200 |
.B AF_INET |
| 201 |
is currently supported for that. |
| 202 |
It is allowed only for IPv6 sockets |
| 203 |
that are connected and bound to a v4-mapped-on-v6 address. |
| 204 |
The argument is a pointer to an integer containing |
| 205 |
.BR AF_INET . |
| 206 |
This is useful to pass v4-mapped sockets as file descriptors to |
| 207 |
programs that don't know how to deal with the IPv6 API. |
| 208 |
.TP |
| 209 |
.B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP |
| 210 |
Control membership in multicast groups. |
| 211 |
Argument is a pointer to a |
| 212 |
.IR "struct ipv6_mreq" . |
| 213 |
.TP |
| 214 |
.B IPV6_MTU |
| 215 |
.BR getsockopt (): |
| 216 |
Retrieve the current known path MTU of the current socket. |
| 217 |
Valid only when the socket has been connected. |
| 218 |
Returns an integer. |
| 219 |
.IP |
| 220 |
.BR setsockopt (): |
| 221 |
Set the MTU to be used for the socket. |
| 222 |
The MTU is limited by the device |
| 223 |
MTU or the path MTU when path MTU discovery is enabled. |
| 224 |
Argument is a pointer to integer. |
| 225 |
.TP |
| 226 |
.B IPV6_MTU_DISCOVER |
| 227 |
Control path-MTU discovery on the socket. |
| 228 |
See |
| 229 |
.B IP_MTU_DISCOVER |
| 230 |
in |
| 231 |
.BR ip (7) |
| 232 |
for details. |
| 233 |
.TP |
| 234 |
.B IPV6_MULTICAST_HOPS |
| 235 |
Set the multicast hop limit for the socket. |
| 236 |
Argument is a pointer to an |
| 237 |
integer. |
| 238 |
\-1 in the value means use the route default, otherwise it should be |
| 239 |
between 0 and 255. |
| 240 |
.TP |
| 241 |
.B IPV6_MULTICAST_IF |
| 242 |
Set the device for outgoing multicast packets on the socket. |
| 243 |
This is allowed only for |
| 244 |
.B SOCK_DGRAM |
| 245 |
and |
| 246 |
.B SOCK_RAW |
| 247 |
socket. |
| 248 |
The argument is a pointer to an interface index (see |
| 249 |
.BR netdevice (7)) |
| 250 |
in an integer. |
| 251 |
.TP |
| 252 |
.B IPV6_MULTICAST_LOOP |
| 253 |
Control whether the socket sees multicast packets that it has send itself. |
| 254 |
Argument is a pointer to boolean. |
| 255 |
.TP |
| 256 |
.BR IPV6_RECVPKTINFO " (since Linux 2.6.14)" |
| 257 |
Set delivery of the |
| 258 |
.B IPV6_PKTINFO |
| 259 |
control message on incoming datagrams. |
| 260 |
Such control messages contain a |
| 261 |
.IR "struct in6_pktinfo" , |
| 262 |
as per RFC 3542. |
| 263 |
Allowed only for |
| 264 |
.B SOCK_DGRAM |
| 265 |
or |
| 266 |
.B SOCK_RAW |
| 267 |
sockets. |
| 268 |
Argument is a pointer to a boolean value in an integer. |
| 269 |
.TP |
| 270 |
.B \%IPV6_RTHDR, \%IPV6_AUTHHDR, \%IPV6_DSTOPTS, \%IPV6_HOPOPTS, \ |
| 271 |
\%IPV6_FLOWINFO, \%IPV6_HOPLIMIT |
| 272 |
Set delivery of control messages for incoming datagrams containing |
| 273 |
extension headers from the received packet. |
| 274 |
.B IPV6_RTHDR |
| 275 |
delivers the routing header, |
| 276 |
.B IPV6_AUTHHDR |
| 277 |
delivers the authentication header, |
| 278 |
.B IPV6_DSTOPTS |
| 279 |
delivers the destination options, |
| 280 |
.B IPV6_HOPOPTS |
| 281 |
delivers the hop options, |
| 282 |
.B IPV6_FLOWINFO |
| 283 |
delivers an integer containing the flow ID, |
| 284 |
.B IPV6_HOPLIMIT |
| 285 |
delivers an integer containing the hop count of the packet. |
| 286 |
The control messages have the same type as the socket option. |
| 287 |
All these header options can also be set for outgoing packets |
| 288 |
by putting the appropriate control message into the control buffer of |
| 289 |
.BR sendmsg (2). |
| 290 |
Allowed only for |
| 291 |
.B SOCK_DGRAM |
| 292 |
or |
| 293 |
.B SOCK_RAW |
| 294 |
sockets. |
| 295 |
Argument is a pointer to a boolean value. |
| 296 |
.TP |
| 297 |
.B IPV6_RECVERR |
| 298 |
Control receiving of asynchronous error options. |
| 299 |
See |
| 300 |
.B IP_RECVERR |
| 301 |
in |
| 302 |
.BR ip (7) |
| 303 |
for details. |
| 304 |
Argument is a pointer to boolean. |
| 305 |
.TP |
| 306 |
.B IPV6_ROUTER_ALERT |
| 307 |
Pass forwarded packets containing a router alert hop-by-hop option to |
| 308 |
this socket. |
| 309 |
Allowed only for |
| 310 |
.B SOCK_RAW |
| 311 |
sockets. |
| 312 |
The tapped packets are not forwarded by the kernel, it is the |
| 313 |
user's responsibility to send them out again. |
| 314 |
Argument is a pointer to an integer. |
| 315 |
A positive integer indicates a router alert option value to intercept. |
| 316 |
Packets carrying a router alert option with a value field containing |
| 317 |
this integer will be delivered to the socket. |
| 318 |
A negative integer disables delivery of packets with router alert options |
| 319 |
to this socket. |
| 320 |
.TP |
| 321 |
.B IPV6_UNICAST_HOPS |
| 322 |
Set the unicast hop limit for the socket. |
| 323 |
Argument is a pointer to an integer. |
| 324 |
\-1 in the value means use the route default, |
| 325 |
otherwise it should be between 0 and 255. |
| 326 |
.TP |
| 327 |
.BR IPV6_V6ONLY " (since Linux 2.4.21 and 2.6)" |
| 328 |
.\" See RFC 3493 |
| 329 |
If this flag is set to true (nonzero), then the socket is restricted |
| 330 |
to sending and receiving IPv6 packets only. |
| 331 |
In this case, an IPv4 and an IPv6 application can bind |
| 332 |
to a single port at the same time. |
| 333 |
.IP |
| 334 |
If this flag is set to false (zero), |
| 335 |
then the socket can be used to send and receive packets |
| 336 |
to and from an IPv6 address or an IPv4-mapped IPv6 address. |
| 337 |
.IP |
| 338 |
The argument is a pointer to a boolean value in an integer. |
| 339 |
.IP |
| 340 |
The default value for this flag is defined by the contents of the file |
| 341 |
.IR /proc/sys/net/ipv6/bindv6only . |
| 342 |
The default value for that file is 0 (false). |
| 343 |
.\" FLOWLABEL_MGR, FLOWINFO_SEND |
| 344 |
.SH ERRORS |
| 345 |
.TP |
| 346 |
.B ENODEV |
| 347 |
The user tried to |
| 348 |
.BR bind (2) |
| 349 |
to a link-local IPv6 address, but the |
| 350 |
.I sin6_scope_id |
| 351 |
in the supplied |
| 352 |
.I sockaddr_in6 |
| 353 |
structure is not a valid |
| 354 |
interface index. |
| 355 |
.SH VERSIONS |
| 356 |
Linux 2.4 will break binary compatibility for the |
| 357 |
.I sockaddr_in6 |
| 358 |
for 64-bit |
| 359 |
hosts by changing the alignment of |
| 360 |
.I in6_addr |
| 361 |
and adding an additional |
| 362 |
.I sin6_scope_id |
| 363 |
field. |
| 364 |
The kernel interfaces stay compatible, but a program including |
| 365 |
.I sockaddr_in6 |
| 366 |
or |
| 367 |
.I in6_addr |
| 368 |
into other structures may not be. |
| 369 |
This is not |
| 370 |
a problem for 32-bit hosts like i386. |
| 371 |
.P |
| 372 |
The |
| 373 |
.I sin6_flowinfo |
| 374 |
field is new in Linux 2.4. |
| 375 |
It is transparently passed/read by the kernel |
| 376 |
when the passed address length contains it. |
| 377 |
Some programs that pass a longer address buffer and then |
| 378 |
check the outgoing address length may break. |
| 379 |
.SH NOTES |
| 380 |
The |
| 381 |
.I sockaddr_in6 |
| 382 |
structure is bigger than the generic |
| 383 |
.IR sockaddr . |
| 384 |
Programs that assume that all address types can be stored safely in a |
| 385 |
.I struct sockaddr |
| 386 |
need to be changed to use |
| 387 |
.I struct sockaddr_storage |
| 388 |
for that instead. |
| 389 |
.P |
| 390 |
.BR SOL_IP , |
| 391 |
.BR SOL_IPV6 , |
| 392 |
.BR SOL_ICMPV6 , |
| 393 |
and other |
| 394 |
.B SOL_* |
| 395 |
socket options are nonportable variants of |
| 396 |
.BR IPPROTO_* . |
| 397 |
See also |
| 398 |
.BR ip (7). |
| 399 |
.SH BUGS |
| 400 |
The IPv6 extended API as in RFC\ 2292 is currently only partly |
| 401 |
implemented; |
| 402 |
although the 2.2 kernel has near complete support for receiving options, |
| 403 |
the macros for generating IPv6 options are missing in glibc 2.1. |
| 404 |
.P |
| 405 |
IPSec support for EH and AH headers is missing. |
| 406 |
.P |
| 407 |
Flow label management is not complete and not documented here. |
| 408 |
.P |
| 409 |
This man page is not complete. |
| 410 |
.SH SEE ALSO |
| 411 |
.BR cmsg (3), |
| 412 |
.BR ip (7) |
| 413 |
.P |
| 414 |
RFC\ 2553: IPv6 BASIC API; |
| 415 |
Linux tries to be compliant to this. |
| 416 |
RFC\ 2460: IPv6 specification. |