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