inet6(4)

NAME

inet6 - Internet protocol version 6 family

SYNOPSIS

#include <sys/types.h>
#include <netinet/in.h>

DESCRIPTION

The inet6 family is an updated version of inet(4) family.

While inet(4)
implements Internet Protocol version 4, inet6 implements In

ternet Protocol version 6.

inet6 is a collection of protocols layered atop the Internet

Protocol
version 6 (IPv6) transport layer, and utilizing the IPv6 ad

dress format.
The inet6 family provides protocol support for the

SOCK_STREAM,
SOCK_DGRAM, and SOCK_RAW socket types; the SOCK_RAW inter

face provides
access to the IPv6 protocol.

ADDRESSING

IPv6 addresses are 16 byte quantities, stored in network

standard byteorder. The include file #include <netinet/in.h> defines this address as a discriminated union.

Sockets bound to the inet6 family utilize the following ad

dressing structure:

struct sockaddr_in6 {

uint8_t sin6_len;
sa_family_t sin6_family;
in_port_t sin6_port;
uint32_t sin6_flowinfo;
struct in6_addr sin6_addr;
uint32_t sin6_scope_id;

};

Sockets may be created with the local address ``::'' (which

is equal to
IPv6 address 0:0:0:0:0:0:0:0) to affect ``wildcard'' match

ing on incoming
messages.

The IPv6 specification defines scoped addresses, like link

local or sitelocal addresses. A scoped address is ambiguous to the ker

nel, if it is
specified without a scope identifier. To manipulate scoped

addresses
properly from the userland, programs must use the advanced

API defined in
RFC2292. A compact description of the advanced API is

available in
ip6(4). If a scoped address is specified without an explic

it scope, the
kernel may raise an error. Note that scoped addresses are

not for daily
use at this moment, both from a specification and an imple

mentation point
of view.

The KAME implementation supports an extended numeric IPv6

address notation for link-local addresses, like ``fe80::1%de0'' to spec

ify ``fe80::1
on de0 interface''. This notation is supported by getad

drinfo(3) and
getnameinfo(3). Some of normal userland programs, such as

telnet(1) or
ftp(1), are able to use this notation. With special pro

grams like
ping6(8), you can specify the outgoing interface by an extra

command line
option to disambiguate scoped addresses.

Scoped addresses are handled specially in the kernel. In

kernel structures like routing tables or interface structures, a scoped

address will
have its interface index embedded into the address. There

fore, the
address in some kernel structures is not the same as that on

the wire.
The embedded index will become visible through a PF_ROUTE

socket, kernel
memory accesses via kvm(3) and on some other occasions.

HOWEVER, users
should never use the embedded form. For details please con

sult
IMPLEMENTATION supplied with KAME kit.

PROTOCOLS

The inet6 family is comprised of the IPv6 network protocol,

Internet Control Message Protocol version 6 (ICMPv6), Transmission Con

trol Protocol
(TCP), and User Datagram Protocol (UDP). TCP is used to

support the
SOCK_STREAM abstraction while UDP is used to support the

SOCK_DGRAM
abstraction. Note that TCP and UDP are common to inet(4)

and inet6. A
raw interface to IPv6 is available by creating an Internet

socket of type
SOCK_RAW. The ICMPv6 message protocol is accessible from a

raw socket.

MIB Variables

A number of variables are implemented in the net.inet6

branch of the
sysctl(3) MIB. In addition to the variables supported by

the transport
protocols (for which the respective manual pages may be con

sulted), the
following general variables are defined:

IPV6CTL_FORWARDING (ip6.forwarding) Boolean: en

able/disable forward

ing of IPv6 packets. Also, identify

if the node
is acting as a router. Defaults to

off.

IPV6CTL_SENDREDIRECTS (ip6.redirect) Boolean: enable/dis

able sending of

ICMPv6 redirects in response to un

forwardable
IPv6 packets. This option is ig

nored unless the
node is routing IPv6 packets, and

should normally
be enabled on all systems. Defaults

to on.

IPV6CTL_DEFHLIM (ip6.hlim) Integer: default hop lim

it value to

use for outgoing IPv6 packets. This

value
applies to all the transport proto

cols on top of
IPv6. There are APIs to override

the value.

IPV6CTL_MAXFRAGPACKETS (ip6.maxfragpackets) Integer: de

fault maximum

number of fragmented packets the

node will
accept. 0 means that the node will

not accept
any fragmented packets. -1 means

that the node
will accept as many fragmented pack

ets as it
receives. The flag is provided ba

sically for
avoiding possible DoS attacks.

IPV6CTL_ACCEPT_RTADV (ip6.accept_rtadv) Boolean: en

able/disable

receiving of ICMPv6 router adver

tisement packets,
and autoconfiguration of address

prefixes and
default routers. The node must be a

host (not a
router) for the option to be mean

ingful.
Defaults to off.

IPV6CTL_KEEPFAITH (ip6.keepfaith) Boolean: enable/dis

able ``FAITH''

TCP relay IPv6-to-IPv4 translator

code in the
kernel. Refer faith(4) and

faithd(8) for detail.
Defaults to off.

IPV6CTL_LOG_INTERVAL (ip6.log_interval) Integer: default

interval

between IPv6 packet forwarding en

gine log output
(in seconds).

IPV6CTL_HDRNESTLIMIT (ip6.hdrnestlimit) Integer: default

number of the

maximum IPv6 extension headers per

mitted on
incoming IPv6 packets. If set to 0,

the node
will accept as many extension head

ers as possible.

IPV6CTL_DAD_COUNT (ip6.dad_count) Integer: default

number of IPv6

DAD (duplicated address detection)

probe packets.
The packets will be generated when

IPv6 interface
addresses are configured.

IPV6CTL_AUTO_FLOWLABEL (ip6.auto_flowlabel) Boolean: en

able/disable

automatic filling of IPv6 flowlabel

field, for
outstanding connected transport pro

tocol packets.
The field might be used by interme

diate routers
to identify packet flows. Defaults

to on.

IPV6CTL_DEFMCASTHLIM (ip6.defmcasthlim) Integer: default

hop limit

value for an IPv6 multicast packet

sourced by the
node. This value applies to all the

transport
protocols on top of IPv6. There are

APIs to
override the value as documented in

ip6(4).

IPV6CTL_GIF_HLIM (ip6.gifhlim) Integer: default maxi

mum hop limit

value for an IPv6 packet generated

by gif(4) tunnel interface.

IPV6CTL_KAME_VERSION (ip6.kame_version) String: identi

fies the version

of KAME IPv6 stack implemented in

the kernel.

IPV6CTL_USE_DEPRECATED (ip6.use_deprecated) Boolean: en

able/disable use

of deprecated address, specified in

RFC2462
5.5.4. Defaults to on.

IPV6CTL_RR_PRUNE (ip6.rr_prune) Integer: default in

terval between

IPv6 router renumbering prefix

babysitting, in
seconds.

IPV6CTL_V6ONLY (ip6.v6only) Boolean: enable/disable

the prohib

ited use of IPv4 mapped address on

AF_INET6 sockets. Defaults to on.

IPV6CTL_RTEXPIRE (ip6.rtexpire) Integer: lifetime in

seconds of

protocol-cloned IP routes after the

last reference drops (default one hour).

IPV6CTL_RTMINEXPIRE (ip6.rtminexpire) Integer: minimum

value of

ip.rtexpire (default ten seconds).

IPV6CTL_RTMAXCACHE (ip6.rtmaxcache) Integer: trigger

level of

cached, unreferenced, protocol

cloned routes
which initiates dynamic adaptation

(default 128).

Interaction between IPv4/v6 sockets

By default, FreeBSD does not route IPv4 traffic to AF_INET6

sockets. The
default behavior intentionally violates RFC2553 for security

reasons.
Listen to two sockets if you want to accept both IPv4 and

IPv6 traffic.
IPv4 traffic may be routed with certain per-socket/per-node

configuration, however, it is not recommended to do so. Consult

ip6(4) for
details.

The behavior of AF_INET6 TCP/UDP socket is documented in

RFC2553. Basically, it says this:
+o A specific bind on an AF_INET6 socket (bind(2) with an

address speci

fied) should accept IPv6 traffic to that address only.

+o If you perform a wildcard bind on an AF_INET6 socket

(bind(2) to IPv6

address ::), and there is no wildcard bind AF_INET sock

et on that
TCP/UDP port, IPv6 traffic as well as IPv4 traffic

should be routed
to that AF_INET6 socket. IPv4 traffic should be seen as

if it came
from an IPv6 address like ::ffff:10.1.1.1. This is

called an IPv4
mapped address.

+o If there are both a wildcard bind AF_INET socket and a

wildcard bind

AF_INET6 socket on one TCP/UDP port, they should behave

separately.
IPv4 traffic should be routed to the AF_INET socket and

IPv6 should
be routed to the AF_INET6 socket.

However, RFC2553 does not define the ordering constraint be

tween calls to
bind(2), nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP

port numbers
relate to each other (should they be integrated or separat

ed). Implemented behavior is very different from kernel to kernel.

Therefore, it
is unwise to rely too much upon the behavior of AF_INET6

wildcard bind
sockets. It is recommended to listen to two sockets, one

for AF_INET and
another for AF_INET6, when you would like to accept both

IPv4 and IPv6
traffic.

It should also be noted that malicious parties can take ad

vantage of the
complexity presented above, and are able to bypass access

control, if the
target node routes IPv4 traffic to AF_INET6 socket. Users

are advised to
take care handling connections from IPv4 mapped address to

AF_INET6 sockets.

SEE ALSO

ioctl(2), socket(2), sysctl(3), icmp6(4), intro(4), ip6(4),

tcp(4),
udp(4)

STANDARDS

Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for

IPv6 Scoped
Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-for

mat-02.txt,
June 2000, work in progress material.

HISTORY

The inet6 protocol interfaces are defined in RFC2553 and

RFC2292. The
implementation described herein appeared in the WIDE/KAME

project.

BUGS

The IPv6 support is subject to change as the Internet proto

cols develop.
Users should not depend on details of the current implemen

tation, but
rather the services exported.

Users are suggested to implement ``version independent''

code as much as
possible, as you will need to support both inet(4) and

inet6.

BSD January 29, 1999

BSD