xref: /freebsd/share/man/man4/inet6.4 (revision ddd5b8e9b4d8957fce018c520657cdfa4ecffad3)
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 September 2, 2009
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 affect
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 ping6 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 net.inet6 branch of the
189.Xr sysctl 3
190MIB.
191In addition to the variables supported by the transport protocols
192(for which the respective manual pages may be consulted),
193the following general variables are defined:
194.Bl -tag -width IPV6CTL_MAXFRAGPACKETS
195.It Dv IPV6CTL_FORWARDING
196.Pq ip6.forwarding
197Boolean: enable/disable forwarding of
198.Tn IPv6
199packets.
200Also, identify if the node is acting as a router.
201Defaults to off.
202.It Dv IPV6CTL_SENDREDIRECTS
203.Pq ip6.redirect
204Boolean: enable/disable sending of
205.Tn ICMPv6
206redirects in response to unforwardable
207.Tn IPv6
208packets.
209This option is ignored unless the node is routing
210.Tn IPv6
211packets,
212and should normally be enabled on all systems.
213Defaults to on.
214.It Dv IPV6CTL_DEFHLIM
215.Pq ip6.hlim
216Integer: default hop limit value to use for outgoing
217.Tn IPv6
218packets.
219This value applies to all the transport protocols on top of
220.Tn IPv6 .
221There are APIs to override the value.
222.It Dv IPV6CTL_MAXFRAGPACKETS
223.Pq ip6.maxfragpackets
224Integer: default maximum number of fragmented packets the node will accept.
2250 means that the node will not accept any fragmented packets.
226-1 means that the node will accept as many fragmented packets as it receives.
227The flag is provided basically for avoiding possible DoS attacks.
228.It Dv IPV6CTL_ACCEPT_RTADV
229.Pq ip6.accept_rtadv
230Boolean: the default value of a per-interface flag to
231enable/disable receiving of
232.Tn ICMPv6
233router advertisement packets,
234and autoconfiguration of address prefixes and default routers.
235The node must be a host
236(not a router)
237for the option to be meaningful.
238Defaults to off.
239.It Dv IPV6CTL_AUTO_LINKLOCAL
240.Pq ip6.auto_linklocal
241Boolean: the default value of a per-interface flag to
242enable/disable performing automatic link-local address configuration.
243Defaults to on.
244.It Dv IPV6CTL_KEEPFAITH
245.Pq ip6.keepfaith
246Boolean: enable/disable
247.Dq FAITH
248TCP relay IPv6-to-IPv4 translator code in the kernel.
249Refer
250.Xr faith 4
251and
252.Xr faithd 8
253for detail.
254Defaults to off.
255.It Dv IPV6CTL_LOG_INTERVAL
256.Pq ip6.log_interval
257Integer: default interval between
258.Tn IPv6
259packet forwarding engine log output
260(in seconds).
261.It Dv IPV6CTL_HDRNESTLIMIT
262.Pq ip6.hdrnestlimit
263Integer: default number of the maximum
264.Tn IPv6
265extension headers
266permitted on incoming
267.Tn IPv6
268packets.
269If set to 0, the node will accept as many extension headers as possible.
270.It Dv IPV6CTL_DAD_COUNT
271.Pq ip6.dad_count
272Integer: default number of
273.Tn IPv6
274DAD
275.Pq duplicated address detection
276probe packets.
277The packets will be generated when
278.Tn IPv6
279interface addresses are configured.
280.It Dv IPV6CTL_AUTO_FLOWLABEL
281.Pq ip6.auto_flowlabel
282Boolean: enable/disable automatic filling of
283.Tn IPv6
284flowlabel field, for outstanding connected transport protocol packets.
285The field might be used by intermediate routers to identify packet flows.
286Defaults to on.
287.It Dv IPV6CTL_DEFMCASTHLIM
288.Pq ip6.defmcasthlim
289Integer: default hop limit value for an
290.Tn IPv6
291multicast packet sourced by the node.
292This value applies to all the transport protocols on top of
293.Tn IPv6 .
294There are APIs to override the value as documented in
295.Xr ip6 4 .
296.It Dv IPV6CTL_GIF_HLIM
297.Pq ip6.gifhlim
298Integer: default maximum hop limit value for an
299.Tn IPv6
300packet generated by
301.Xr gif 4
302tunnel interface.
303.It Dv IPV6CTL_KAME_VERSION
304.Pq ip6.kame_version
305String: identifies the version of KAME
306.Tn IPv6
307stack implemented in the kernel.
308.It Dv IPV6CTL_USE_DEPRECATED
309.Pq ip6.use_deprecated
310Boolean: enable/disable use of deprecated address,
311specified in RFC2462 5.5.4.
312Defaults to on.
313.It Dv IPV6CTL_RR_PRUNE
314.Pq ip6.rr_prune
315Integer: default interval between
316.Tn IPv6
317router renumbering prefix babysitting, in seconds.
318.It Dv IPV6CTL_V6ONLY
319.Pq ip6.v6only
320Boolean: enable/disable the prohibited use of
321.Tn IPv4
322mapped address on
323.Dv AF_INET6
324sockets.
325Defaults to on.
326.It Dv IPV6CTL_RTEXPIRE
327.Pq ip6.rtexpire
328Integer: lifetime in seconds of protocol-cloned
329.Tn IP
330routes after the last reference drops (default one hour).
331.\"This value varies dynamically as described above.
332.It Dv IPV6CTL_RTMINEXPIRE
333.Pq ip6.rtminexpire
334Integer: minimum value of ip.rtexpire (default ten seconds).
335.\"This value has no effect on user modifications, but restricts the dynamic
336.\"adaptation described above.
337.It Dv IPV6CTL_RTMAXCACHE
338.Pq ip6.rtmaxcache
339Integer: trigger level of cached, unreferenced, protocol-cloned routes
340which initiates dynamic adaptation (default 128).
341.El
342.Ss Interaction between IPv4/v6 sockets
343By default,
344.Fx
345does not route IPv4 traffic to
346.Dv AF_INET6
347sockets.
348The default behavior intentionally violates RFC2553 for security reasons.
349Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
350IPv4 traffic may be routed with certain
351per-socket/per-node configuration, however, it is not recommended to do so.
352Consult
353.Xr ip6 4
354for details.
355.Pp
356The behavior of
357.Dv AF_INET6
358TCP/UDP socket is documented in RFC2553.
359Basically, it says this:
360.Bl -bullet -compact
361.It
362A specific bind on an
363.Dv AF_INET6
364socket
365.Xr ( bind 2
366with an address specified)
367should accept IPv6 traffic to that address only.
368.It
369If you perform a wildcard bind
370on an
371.Dv AF_INET6
372socket
373.Xr ( bind 2
374to IPv6 address
375.Li :: ) ,
376and there is no wildcard bind
377.Dv AF_INET
378socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
379should be routed to that
380.Dv AF_INET6
381socket.
382IPv4 traffic should be seen as if it came from an IPv6 address like
383.Li ::ffff:10.1.1.1 .
384This is called an IPv4 mapped address.
385.It
386If there are both a wildcard bind
387.Dv AF_INET
388socket and a wildcard bind
389.Dv AF_INET6
390socket on one TCP/UDP port, they should behave separately.
391IPv4 traffic should be routed to the
392.Dv AF_INET
393socket and IPv6 should be routed to the
394.Dv AF_INET6
395socket.
396.El
397.Pp
398However, RFC2553 does not define the ordering constraint between calls to
399.Xr bind 2 ,
400nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers
401relate to each other
402(should they be integrated or separated).
403Implemented behavior is very different from kernel to kernel.
404Therefore, it is unwise to rely too much upon the behavior of
405.Dv AF_INET6
406wildcard bind sockets.
407It is recommended to listen to two sockets, one for
408.Dv AF_INET
409and another for
410.Dv AF_INET6 ,
411when you would like to accept both IPv4 and IPv6 traffic.
412.Pp
413It should also be noted that
414malicious parties can take advantage of the complexity presented above,
415and are able to bypass access control,
416if the target node routes IPv4 traffic to
417.Dv AF_INET6
418socket.
419Users are advised to take care handling connections
420from IPv4 mapped address to
421.Dv AF_INET6
422sockets.
423.Sh SEE ALSO
424.Xr ioctl 2 ,
425.Xr socket 2 ,
426.Xr sysctl 3 ,
427.Xr icmp6 4 ,
428.Xr intro 4 ,
429.Xr ip6 4 ,
430.Xr tcp 4 ,
431.Xr udp 4
432.Sh STANDARDS
433.Rs
434.%A Tatsuya Jinmei
435.%A Atsushi Onoe
436.%T "An Extension of Format for IPv6 Scoped Addresses"
437.%R internet draft
438.%D June 2000
439.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
440.%O work in progress material
441.Re
442.Sh HISTORY
443The
444.Nm
445protocol interfaces are defined in RFC2553 and RFC2292.
446The implementation described herein appeared in the WIDE/KAME project.
447.Sh BUGS
448The IPv6 support is subject to change as the Internet protocols develop.
449Users should not depend on details of the current implementation,
450but rather the services exported.
451.Pp
452Users are suggested to implement
453.Dq version independent
454code as much as possible, as you will need to support both
455.Xr inet 4
456and
457.Nm .
458