]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man4/inet6.4
xnu-6153.141.1.tar.gz
[apple/xnu.git] / bsd / man / man4 / inet6.4
... / ...
CommitLineData
1.\" $FreeBSD: src/share/man/man4/inet6.4,v 1.4.2.8 2001/12/17 11:30:12 ru 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 January 29, 1999
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
41The
42.Nm
43family is an updated version of
44.Xr inet 4
45family.
46While
47.Xr inet 4
48implements Internet Protocol version 4,
49.Nm
50implements Internet Protocol version 6.
51.Pp
52.Nm
53is a collection of protocols layered atop the
54.Em Internet Protocol version 6
55.Pq Tn IPv6
56transport layer, and utilizing the IPv6 address format.
57The
58.Nm
59family provides protocol support for the
60.Dv SOCK_STREAM , SOCK_DGRAM ,
61and
62.Dv SOCK_RAW
63socket types; the
64.Dv SOCK_RAW
65interface provides access to the
66.Tn IPv6
67protocol.
68.Sh ADDRESSING
69IPv6 addresses are 16 byte quantities, stored in network standard byteorder.
70The include file
71.Aq Pa netinet/in.h
72defines this address
73as a discriminated union.
74.Pp
75Sockets bound to the
76.Nm
77family utilize the following addressing structure:
78.Bd -literal -offset indent
79struct sockaddr_in6 {
80 u_int8_t sin6_len;
81 u_int8_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
89Sockets 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 )
93to affect
94.Dq wildcard
95matching on incoming messages.
96.Pp
97The IPv6 specification defines scoped addresses,
98like link-local or site-local addresses.
99A scoped address is ambiguous to the kernel,
100if it is specified without a scope identifier.
101To manipulate scoped addresses properly from the userland,
102programs must use the advanced API defined in RFC2292.
103A compact description of the advanced API is available in
104.Xr ip6 4 .
105If a scoped address is specified without an explicit scope,
106the kernel may raise an error.
107Note that scoped addresses are not for daily use at this moment,
108both from a specification and an implementation point of view.
109.Pp
110The KAME implementation supports an extended numeric IPv6 address notation
111for link-local addresses,
112like
113.Dq Li fe80::1%de0
114to specify
115.Do
116.Li fe80::1
117on
118.Li de0
119interface
120.Dc .
121This notation is supported by
122.Xr getaddrinfo 3
123and
124.Xr getnameinfo 3 .
125Some of normal userland programs, such as
126.Xr telnet 1
127or
128.Xr ftp 1 ,
129are able to use this notation.
130With special programs
131like
132.Xr ping6 8 ,
133you can specify the outgoing interface by an extra command line option
134to disambiguate scoped addresses.
135.Pp
136Scoped addresses are handled specially in the kernel.
137In kernel structures like routing tables or interface structures,
138a scoped address will have its interface index embedded into the address.
139Therefore,
140the address in some kernel structures is not the same as that on the wire.
141The embedded index will become visible through a
142.Dv PF_ROUTE
143socket, kernel memory accesses via
144.Xr kvm 3
145and on some other occasions.
146HOWEVER, users should never use the embedded form.
147For details please consult
148.Pa IMPLEMENTATION
149supplied with KAME kit.
150.Sh PROTOCOLS
151The
152.Nm
153family is comprised of the
154.Tn IPv6
155network protocol, Internet Control
156Message Protocol version 6
157.Pq Tn ICMPv6 ,
158Transmission Control Protocol
159.Pq Tn TCP ,
160and User Datagram Protocol
161.Pq Tn UDP .
162.Tn TCP
163is used to support the
164.Dv SOCK_STREAM
165abstraction while
166.Tn UDP
167is used to support the
168.Dv SOCK_DGRAM
169abstraction.
170Note that
171.Tn TCP
172and
173.Tn UDP
174are common to
175.Xr inet 4
176and
177.Nm .
178A raw interface to
179.Tn IPv6
180is available
181by creating an Internet socket of type
182.Dv SOCK_RAW .
183The
184.Tn ICMPv6
185message 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 3/4, 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
267A number of variables are implemented in the net.inet6 branch of the
268.Xr sysctl 3
269MIB.
270In addition to the variables supported by the transport protocols
271(for which the respective manual pages may be consulted),
272the following general variables are defined:
273.Bl -tag -width IPV6CTL_MAXFRAGPACKETS
274.It Dv IPV6CTL_FORWARDING
275.Pq ip6.forwarding
276Boolean: enable/disable forwarding of
277.Tn IPv6
278packets.
279Also, identify if the node is acting as a router.
280Defaults to off.
281.It Dv IPV6CTL_SENDREDIRECTS
282.Pq ip6.redirect
283Boolean: enable/disable sending of
284.Tn ICMPv6
285redirects in response to unforwardable
286.Tn IPv6
287packets.
288This option is ignored unless the node is routing
289.Tn IPv6
290packets,
291and should normally be enabled on all systems.
292Defaults to on.
293.It Dv IPV6CTL_DEFHLIM
294.Pq ip6.hlim
295Integer: default hop limit value to use for outgoing
296.Tn IPv6
297packets.
298This value applies to all the transport protocols on top of
299.Tn IPv6 .
300There are APIs to override the value.
301.It Dv IPV6CTL_MAXFRAGPACKETS
302.Pq ip6.maxfragpackets
303Integer: default maximum number of fragmented packets the node will accept.
3040 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.
306The flag is provided basically for avoiding possible DoS attacks.
307.It Dv IPV6CTL_ACCEPT_RTADV
308.Pq ip6.accept_rtadv
309Boolean: enable/disable receiving of
310.Tn ICMPv6
311router advertisement packets,
312and autoconfiguration of address prefixes and default routers.
313The node must be a host
314(not a router)
315for the option to be meaningful.
316Defaults to off.
317.\".It Dv IPV6CTL_KEEPFAITH
318.\".Pq ip6.keepfaith
319.\"Boolean: enable/disable
320.\".Dq FAITH
321.\"TCP relay IPv6-to-IPv4 translator code in the kernel.
322.\"Refer
323.\".Xr faith 4
324.\"and
325.\".Xr faithd 8
326.\"for detail.
327.\"Defaults to off.
328.It Dv IPV6CTL_LOG_INTERVAL
329.Pq ip6.log_interval
330Integer: default interval between
331.Tn IPv6
332packet forwarding engine log output
333(in seconds).
334.It Dv IPV6CTL_HDRNESTLIMIT
335.Pq ip6.hdrnestlimit
336Integer: default number of the maximum
337.Tn IPv6
338extension headers
339permitted on incoming
340.Tn IPv6
341packets.
342If set to 0, the node will accept as many extension headers as possible.
343.It Dv IPV6CTL_DAD_COUNT
344.Pq ip6.dad_count
345Integer: default number of
346.Tn IPv6
347DAD
348.Pq duplicated address detection
349probe packets.
350The packets will be generated when
351.Tn IPv6
352interface addresses are configured.
353.It Dv IPV6CTL_AUTO_FLOWLABEL
354.Pq ip6.auto_flowlabel
355Boolean: enable/disable automatic filling of
356.Tn IPv6
357flowlabel field, for outstanding connected transport protocol packets.
358The field might be used by intermediate routers to identify packet flows.
359Defaults to on.
360.It Dv IPV6CTL_DEFMCASTHLIM
361.Pq ip6.defmcasthlim
362Integer: default hop limit value for an
363.Tn IPv6
364multicast packet sourced by the node.
365This value applies to all the transport protocols on top of
366.Tn IPv6 .
367There are APIs to override the value as documented in
368.Xr ip6 4 .
369.It Dv IPV6CTL_GIF_HLIM
370.Pq ip6.gifhlim
371Integer: default maximum hop limit value for an
372.Tn IPv6
373packet generated by
374.Xr gif 4
375tunnel interface.
376.It Dv IPV6CTL_KAME_VERSION
377.Pq ip6.kame_version
378String: identifies the version of KAME
379.Tn IPv6
380stack implemented in the kernel.
381.It Dv IPV6CTL_USE_DEPRECATED
382.Pq ip6.use_deprecated
383Boolean: enable/disable use of deprecated address,
384specified in RFC2462 5.5.4.
385Defaults to on.
386.It Dv IPV6CTL_RR_PRUNE
387.Pq ip6.rr_prune
388Integer: default interval between
389.Tn IPv6
390router renumbering prefix babysitting, in seconds.
391.It Dv IPV6CTL_MAPPED_ADDR
392.Pq ip6.mapped_addr
393Boolean: enable/disable use of
394.Tn IPv4
395mapped address on
396.Dv AF_INET6
397sockets.
398Defaults to on.
399.It Dv IPV6CTL_RTEXPIRE
400.Pq ip6.rtexpire
401Integer: lifetime in seconds of protocol-cloned
402.Tn IP
403routes after the last reference drops (default one hour).
404.\"This value varies dynamically as described above.
405.It Dv IPV6CTL_RTMINEXPIRE
406.Pq ip6.rtminexpire
407Integer: minimum value of ip.rtexpire (default ten seconds).
408.\"This value has no effect on user modifications, but restricts the dynamic
409.\"adaptation described above.
410.It Dv IPV6CTL_RTMAXCACHE
411.Pq ip6.rtmaxcache
412Integer: trigger level of cached, unreferenced, protocol-cloned routes
413which initiates dynamic adaptation (default 128).
414.El
415.Ss Interaction between IPv4/v6 sockets
416The behavior of
417.Dv AF_INET6
418TCP/UDP socket is documented in RFC2553.
419Basically, it says this:
420.Bl -bullet -compact
421.It
422A specific bind on an
423.Dv AF_INET6
424socket
425.Xr ( bind 2
426with an address specified)
427should accept IPv6 traffic to that address only.
428.It
429If you perform a wildcard bind
430on an
431.Dv AF_INET6
432socket
433.Xr ( bind 2
434to IPv6 address
435.Li :: ) ,
436and there is no wildcard bind
437.Dv AF_INET
438socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic
439should be routed to that
440.Dv AF_INET6
441socket.
442IPv4 traffic should be seen as if it came from an IPv6 address like
443.Li ::ffff:10.1.1.1 .
444This is called an IPv4 mapped address.
445.It
446If there are both a wildcard bind
447.Dv AF_INET
448socket and a wildcard bind
449.Dv AF_INET6
450socket on one TCP/UDP port, they should behave separately.
451IPv4 traffic should be routed to the
452.Dv AF_INET
453socket and IPv6 should be routed to the
454.Dv AF_INET6
455socket.
456.El
457.Pp
458However, RFC2553 does not define the ordering constraint between calls to
459.Xr bind 2 ,
460nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers
461relate to each other
462(should they be integrated or separated).
463Implemented behavior is very different from kernel to kernel.
464Therefore, it is unwise to rely too much upon the behavior of
465.Dv AF_INET6
466wildcard bind sockets.
467It is recommended to listen to two sockets, one for
468.Dv AF_INET
469and another for
470.Dv AF_INET6 ,
471when you would like to accept both IPv4 and IPv6 traffic.
472.Pp
473It should also be noted that
474malicious parties can take advantage of the complexity presented above,
475and are able to bypass access control,
476if the target node routes IPv4 traffic to
477.Dv AF_INET6
478socket.
479Users are advised to take care handling connections
480from IPv4 mapped address to
481.Dv AF_INET6
482sockets.
483.\".Pp
484.\"Because of the above, by default,
485.\"KAME/NetBSD and KAME/OpenBSD
486.\"does not route IPv4 traffic to
487.\".Dv AF_INET6
488.\"sockets.
489.\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic.
490.\"On KAME/NetBSD, IPv4 traffic may be routed with certain
491.\"per-socket/per-node configuration, however, it is not recommended.
492.\"Consult
493.\".Xr ip6 4
494.\"for details.
495.Sh SEE ALSO
496.Xr ioctl 2 ,
497.Xr socket 2 ,
498.Xr sysctl 3 ,
499.Xr icmp6 4 ,
500.Xr intro 4 ,
501.Xr ip6 4 ,
502.Xr tcp 4 ,
503.Xr ttcp 4 ,
504.Xr udp 4
505.Sh STANDARDS
506.Rs
507.%A Tatsuya Jinmei
508.%A Atsushi Onoe
509.%T "An Extension of Format for IPv6 Scoped Addresses"
510.%R internet draft
511.%D June 2000
512.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
513.%O work in progress material
514.Re
515.Sh HISTORY
516The
517.Nm
518protocol interfaces are defined in RFC2553 and RFC2292.
519The implementation described herein appeared in the WIDE/KAME project.
520.Sh BUGS
521The IPv6 support is subject to change as the Internet protocols develop.
522Users should not depend on details of the current implementation,
523but rather the services exported.
524.Pp
525Users are suggested to implement
526.Dq version independent
527code as much as possible, as you will need to support both
528.Xr inet 4
529and
530.Nm .