xref: /freebsd/share/man/man4/inet6.4 (revision d9a42747950146bf03cda7f6e25d219253f8a57a)
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 February 22, 2023
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
42The
43.Nm
44family is an updated version of
45.Xr inet 4
46family.
47While
48.Xr inet 4
49implements Internet Protocol version 4,
50.Nm
51implements Internet Protocol version 6.
52.Pp
53.Nm
54is a collection of protocols layered atop the
55.Em Internet Protocol version 6
56.Pq Tn IPv6
57transport layer, and utilizing the IPv6 address format.
58The
59.Nm
60family provides protocol support for the
61.Dv SOCK_STREAM , SOCK_DGRAM ,
62and
63.Dv SOCK_RAW
64socket types; the
65.Dv SOCK_RAW
66interface provides access to the
67.Tn IPv6
68protocol.
69.Sh ADDRESSING
70IPv6 addresses are 16 byte quantities, stored in network standard byteorder.
71The include file
72.In netinet/in.h
73defines this address
74as a discriminated union.
75.Pp
76Sockets bound to the
77.Nm
78family utilize the following addressing structure:
79.Bd -literal -offset indent
80struct 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
90Sockets 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 )
94to effect
95.Dq wildcard
96matching on incoming messages.
97.Pp
98The IPv6 specification defines scoped addresses,
99like link-local or site-local addresses.
100A scoped address is ambiguous to the kernel,
101if it is specified without a scope identifier.
102To manipulate scoped addresses properly from the userland,
103programs must use the advanced API defined in RFC2292.
104A compact description of the advanced API is available in
105.Xr ip6 4 .
106If a scoped address is specified without an explicit scope,
107the kernel may raise an error.
108Note that scoped addresses are not for daily use at this moment,
109both from a specification and an implementation point of view.
110.Pp
111The KAME implementation supports an extended numeric IPv6 address notation
112for link-local addresses,
113like
114.Dq Li fe80::1%de0
115to specify
116.Do
117.Li fe80::1
118on
119.Li de0
120interface
121.Dc .
122This notation is supported by
123.Xr getaddrinfo 3
124and
125.Xr getnameinfo 3 .
126Some of normal userland programs, such as
127.Xr telnet 1
128or
129.Xr ftp 1 ,
130are able to use this notation.
131With special programs
132like
133.Xr ping 8 ,
134you can specify the outgoing interface by an extra command line option
135to disambiguate scoped addresses.
136.Pp
137Scoped addresses are handled specially in the kernel.
138In kernel structures like routing tables or interface structures,
139a scoped address will have its interface index embedded into the address.
140Therefore,
141the address in some kernel structures is not the same as that on the wire.
142The embedded index will become visible through a
143.Dv PF_ROUTE
144socket, kernel memory accesses via
145.Xr kvm 3
146and on some other occasions.
147HOWEVER, users should never use the embedded form.
148For details please consult
149.Pa IMPLEMENTATION
150supplied with KAME kit.
151.Sh PROTOCOLS
152The
153.Nm
154family is comprised of the
155.Tn IPv6
156network protocol, Internet Control
157Message Protocol version 6
158.Pq Tn ICMPv6 ,
159Transmission Control Protocol
160.Pq Tn TCP ,
161and User Datagram Protocol
162.Pq Tn UDP .
163.Tn TCP
164is used to support the
165.Dv SOCK_STREAM
166abstraction while
167.Tn UDP
168is used to support the
169.Dv SOCK_DGRAM
170abstraction.
171Note that
172.Tn TCP
173and
174.Tn UDP
175are common to
176.Xr inet 4
177and
178.Nm .
179A raw interface to
180.Tn IPv6
181is available
182by creating an Internet socket of type
183.Dv SOCK_RAW .
184The
185.Tn ICMPv6
186message protocol is accessible from a raw socket.
187.Ss MIB Variables
188A number of variables are implemented in the
189.Va net.inet6
190branch of the
191.Xr sysctl 3
192MIB.
193In addition to the variables supported by the transport protocols
194(for which the respective manual pages may be consulted),
195the following general variables are defined:
196.Bl -tag -width IPV6CTL_MAXFRAGPACKETS
197.It Dv IPV6CTL_FORWARDING
198.Pq ip6.forwarding
199Boolean: enable/disable forwarding of
200.Tn IPv6
201packets.
202Also, identify if the node is acting as a router.
203Defaults to off.
204.It Dv IPV6CTL_SENDREDIRECTS
205.Pq ip6.redirect
206Boolean: enable/disable sending of
207.Tn ICMPv6
208redirects in response to unforwardable
209.Tn IPv6
210packets.
211This option is ignored unless the node is routing
212.Tn IPv6
213packets,
214and should normally be enabled on all systems.
215Defaults to on.
216.It Dv IPV6CTL_DEFHLIM
217.Pq ip6.hlim
218Integer: default hop limit value to use for outgoing
219.Tn IPv6
220packets.
221This value applies to all the transport protocols on top of
222.Tn IPv6 .
223There are APIs to override the value.
224.It Dv IPV6CTL_MAXFRAGS
225.Pq ip6.maxfrags
226Integer: maximum number of fragments the host will accept and simultaneously
227hold across all reassembly queues in all VNETs.
228If set to 0, fragment reassembly is disabled.
229If set to -1, this limit is not applied.
230This limit is recalculated when the number of mbuf clusters is changed.
231This is a global limit.
232.It Dv IPV6CTL_MAXFRAGPACKETS
233.Pq ip6.maxfragpackets
234Integer: maximum number of fragmented packets the node will accept and
235simultaneously hold in the reassembly queue for a particular VNET.
2360 means that the node will not accept any fragmented packets for that VNET.
237-1 means that the node will not apply this limit for that VNET.
238This limit is recalculated when the number of mbuf clusters is changed.
239This is a per-VNET limit.
240.It Dv IPV6CTL_MAXFRAGBUCKETSIZE
241.Pq ip6.maxfragbucketsize
242Integer: maximum number of reassembly queues per bucket.
243Fragmented packets are hashed to buckets.
244Each bucket has a list of reassembly queues.
245The system must compare the incoming packets to the existing reassembly queues
246in the bucket to find a matching reassembly queue.
247To preserve system resources, the system limits the number of reassembly
248queues allowed in each bucket.
249This limit is recalculated when the number of mbuf clusters is changed or
250when the value of
251.Va ip6.maxfragpackets
252changes.
253This is a per-VNET limit.
254.It Dv IPV6CTL_MAXFRAGSPERPACKET
255.Pq ip6.maxfragsperpacket
256Integer: maximum number of fragments the host will accept and hold in the
257ressembly queue for a packet.
258This is a per-VNET limit.
259.It Dv IPV6CTL_ACCEPT_RTADV
260.Pq ip6.accept_rtadv
261Boolean: the default value of a per-interface flag to
262enable/disable receiving of
263.Tn ICMPv6
264router advertisement packets,
265and autoconfiguration of address prefixes and default routers.
266The node must be a host
267(not a router)
268for the option to be meaningful.
269Defaults to off.
270.It Dv IPV6CTL_AUTO_LINKLOCAL
271.Pq ip6.auto_linklocal
272Boolean: the default value of a per-interface flag to
273enable/disable performing automatic link-local address configuration.
274Defaults to on.
275.It Dv IPV6CTL_LOG_INTERVAL
276.Pq ip6.log_interval
277Integer: default interval between
278.Tn IPv6
279packet forwarding engine log output
280(in seconds).
281.It Dv IPV6CTL_HDRNESTLIMIT
282.Pq ip6.hdrnestlimit
283Integer: default number of the maximum
284.Tn IPv6
285extension headers
286permitted on incoming
287.Tn IPv6
288packets.
289If set to 0, the node will accept as many extension headers as possible.
290.It Dv IPV6CTL_DAD_COUNT
291.Pq ip6.dad_count
292Integer: default number of
293.Tn IPv6
294DAD
295.Pq duplicated address detection
296probe packets.
297The packets will be generated when
298.Tn IPv6
299interface addresses are configured.
300.It Dv IPV6CTL_AUTO_FLOWLABEL
301.Pq ip6.auto_flowlabel
302Boolean: enable/disable automatic filling of
303.Tn IPv6
304flowlabel field, for outstanding connected transport protocol packets.
305The field might be used by intermediate routers to identify packet flows.
306Defaults to on.
307.It Dv IPV6CTL_DEFMCASTHLIM
308.Pq ip6.defmcasthlim
309Integer: default hop limit value for an
310.Tn IPv6
311multicast packet sourced by the node.
312This value applies to all the transport protocols on top of
313.Tn IPv6 .
314There are APIs to override the value as documented in
315.Xr ip6 4 .
316.It Dv IPV6CTL_GIF_HLIM
317.Pq ip6.gifhlim
318Integer: default maximum hop limit value for an
319.Tn IPv6
320packet generated by
321.Xr gif 4
322tunnel interface.
323.It Dv IPV6CTL_KAME_VERSION
324.Pq ip6.kame_version
325String: identifies the version of KAME
326.Tn IPv6
327stack implemented in the kernel.
328.It Dv IPV6CTL_USE_DEPRECATED
329.Pq ip6.use_deprecated
330Boolean: enable/disable use of deprecated address,
331specified in RFC2462 5.5.4.
332Defaults to on.
333.It Dv IPV6CTL_RR_PRUNE
334.Pq ip6.rr_prune
335Integer: default interval between
336.Tn IPv6
337router renumbering prefix babysitting, in seconds.
338.It Dv IPV6CTL_V6ONLY
339.Pq ip6.v6only
340Boolean: enable/disable the prohibited use of
341.Tn IPv4
342mapped address on
343.Dv AF_INET6
344sockets.
345Defaults to on.
346.It Va ip6.log_cannot_forward
347Boolean: log packets that can't be forwarded because of unspecified source
348address or destination address beyond the scope of the source address as
349described in RFC4443.
350Enabled by default.
351.It Va ip6.source_address_validation
352Boolean: perform source address validation for packets destined for the local
353host.
354Consider this as following Section 3.2 of RFC3704/BCP84, where we treat local
355host as our own infrastructure.
356This has no effect on packets to be forwarded, so don't consider it as
357anti-spoof feature for a router.
358Enabled by default.
359.El
360.Ss Interaction between IPv4/v6 sockets
361By default,
362.Fx
363does not route IPv4 traffic to
364.Dv AF_INET6
365sockets.
366The default behavior intentionally violates RFC2553 for security reasons.
367Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
368IPv4 traffic may be routed with certain
369per-socket/per-node configuration, however, it is not recommended to do so.
370Consult
371.Xr ip6 4
372for details.
373.Pp
374The behavior of
375.Dv AF_INET6
376TCP/UDP socket is documented in RFC2553.
377Basically, it says this:
378.Bl -bullet -compact
379.It
380A specific bind on an
381.Dv AF_INET6
382socket
383.Xr ( bind 2
384with an address specified)
385should accept IPv6 traffic to that address only.
386.It
387If you perform a wildcard bind
388on an
389.Dv AF_INET6
390socket
391.Xr ( bind 2
392to IPv6 address
393.Li :: ) ,
394and there is no wildcard bind
395.Dv AF_INET
396socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
397should be routed to that
398.Dv AF_INET6
399socket.
400IPv4 traffic should be seen as if it came from an IPv6 address like
401.Li ::ffff:10.1.1.1 .
402This is called an IPv4 mapped address.
403.It
404If there are both a wildcard bind
405.Dv AF_INET
406socket and a wildcard bind
407.Dv AF_INET6
408socket on one TCP/UDP port, they should behave separately.
409IPv4 traffic should be routed to the
410.Dv AF_INET
411socket and IPv6 should be routed to the
412.Dv AF_INET6
413socket.
414.El
415.Pp
416However, RFC2553 does not define the ordering constraint between calls to
417.Xr bind 2 ,
418nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers
419relate to each other
420(should they be integrated or separated).
421Implemented behavior is very different from kernel to kernel.
422Therefore, it is unwise to rely too much upon the behavior of
423.Dv AF_INET6
424wildcard bind sockets.
425It is recommended to listen to two sockets, one for
426.Dv AF_INET
427and another for
428.Dv AF_INET6 ,
429when you would like to accept both IPv4 and IPv6 traffic.
430.Pp
431It should also be noted that
432malicious parties can take advantage of the complexity presented above,
433and are able to bypass access control,
434if the target node routes IPv4 traffic to
435.Dv AF_INET6
436socket.
437Users are advised to take care handling connections
438from IPv4 mapped address to
439.Dv AF_INET6
440sockets.
441.Sh SEE ALSO
442.Xr ioctl 2 ,
443.Xr socket 2 ,
444.Xr sysctl 3 ,
445.Xr icmp6 4 ,
446.Xr intro 4 ,
447.Xr ip6 4 ,
448.Xr tcp 4 ,
449.Xr udp 4
450.Rs
451.%A A. Conta
452.%A S. Deering
453.%A M. Gupta
454.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \
455    "Protocol Version 6 (IPv6) Specification"
456.%R RFC 4443
457.%D March 2006
458.Re
459.Sh STANDARDS
460.Rs
461.%A Tatsuya Jinmei
462.%A Atsushi Onoe
463.%T "An Extension of Format for IPv6 Scoped Addresses"
464.%R internet draft
465.%D June 2000
466.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
467.%O work in progress material
468.Re
469.Sh HISTORY
470The
471.Nm
472protocol interfaces are defined in RFC2553 and RFC2292.
473The implementation described herein appeared in the WIDE/KAME project.
474.Sh BUGS
475The IPv6 support is subject to change as the Internet protocols develop.
476Users should not depend on details of the current implementation,
477but rather the services exported.
478.Pp
479Users are suggested to implement
480.Dq version independent
481code as much as possible, as you will need to support both
482.Xr inet 4
483and
484.Nm .
485