tun(7M) STREAMS Modules tun(7M)
NAME
tun, 6to4, 6to4tun, atun - tunneling STREAMS module
SYNOPSIS
strmod/tun
strmod/atun
strmod/6to4tun
DESCRIPTION
tun, atun and 6to4tun are STREAMS modules that implement an IP-in-IP tunneling mechanism. IPv6-in-IPv4, IPv4-in-IPv4, IPv4-in-IPv6 and
IPv6-in-IPv6 tunnels are supported.
Tunnels are configured as point-to-point interfaces. Ipv4-in-Ipv4 allows IPv4 packets to be encapsulated within IPv4 packets. IPv6-in-IPv4
tunnels allow IPv6 packets to be encapsulated within IPv4 packets. IPv4-in-IPv6 tunnels allow IPv4 packets to be encapsulated within IPv6
packets. IPv6-in-IPv6 tunnels allow IPv6 packets to be encapsulated within IPv6 packets. Both the tunnel source and the tunnel destination
are required to configure these type of tunnels. Configured tunnels support encapsulated multicast packets. See ifconfig(1M) for examples
of these tunnel configurations.
The atun module is used to configure automatic tunnels. It supports IPv6 packets encapsulated within IPv4 packets. An IPv4 address is
required for the tunnel source of these interfaces and the IPv4 compatible IPv6 source address must match this address. IPv6 packets
using this interface must have IPv4 compatible source and destination addresses. Automatic tunnels are not point-to-point, and they do
not allow multicast packets to be sent. If the destination of an automatic tunnel is a router, the packets will not be forwarded.
The 6to4tun module is used to configure 6to4 tunnels as described in RFC 3056. It implements automatic tunneling of IPv6 within IPv4. This
IPv6 transition mechanism allows isolated IPv6 networks or nodes attached to an IPv4 network to communicate with other IPv6 networks with
little configuration. See ifconfig(1M) for an example of how to configure a 6to4 tunnel.
o Network startup scripts look at /etc/hostname.ip.*, /etc/hostname6.ip.*, /etc/hostname.ip6.* and /etc/hostname6.ip6.* to find
the available tunneling interfaces.
o The same tunnel source address (tsrc) and destination address (tdst) is be used for all instances (luns) of a specific
interface.
o Tunnels do not support snooping. Instead, a filter made up of the combination of addresses can be used on the physical inter-
face to capture relevant packets.
o If there is a tunnel set up between two multicast routers, then multicast routing should be configured to use the tunnel, rather
than a special multicast routing virtual interface.
APPLICATION PROGRAMMING INTEFACE
The tunnel module is architected to be plumbed between two instances of IP.
IOCTLS
The following ioctl() calls may be used to configure a tunneling interface. The ioctl()s are defined in <sys/sockio.h>. This structure is
defined in <net/if.h>.
/* currently tunnels only support IPv4 or IPv6 */
enum ifta_proto {
IFTAP_INVALID,
IFTAP_IPV4,
IFTAP_IPV6
};
#define IFTUN_SECINFOLEN 8
#define IFTUN_VERSION 1
/* tunnel configuration structure */
struct iftun_req {
char ifta_lifr_name[LIFNAMSIZ]; /* if name */
struct sockaddr_storage ifta_saddr; /* source address */
struct sockaddr_storage ifta_daddr; /* destination address */
uint_t ifta_flags; /* See below */
/* IP version information is read only */
enum ifta_proto ifta_upper; /* IP version above tunnel */
enum ifta_proto ifta_lower; /* IP versin below tunnel */
uint_t ifta_vers; /* Version number */
uint32_t ifta_secinfo[IFTUN_SECINFOLEN]; /* Security prefs. */
int16_t ifta_encap_lim; /* Encapsulation limit */
uint8_t ifta_hop_limit; /* Hop limit */
};
/* These flags are set to indicate which members are valid */
#define IFTUN_SRC 0x01
#define IFTUN_DST 0x02
#define IFTUN_SECURITY 0x04
#define IFTUN_ENCAP 0x08
#define IFTUN_HOPLIMIT 0x10
The ifta_vers field indicates what IPsec request structure is overlayed on top of ifta_secinfo. The current value of IFTUN_VERSION implies
an overlay of ipsec_req_t. See ipsec(7P).
SIOCSTUNPARAM Set tunnel parameters. This ioctl() allows the tunnel's source or destination address or hop limit or encapsulation limit
to be set. The IFTUN_SRC bit set in ta_flags indicates that the tunnel should bound to the source address supplied in
ta_saddr. The source must be a valid configured interface IP address. The IFTUN_DST bit set in ta_flags indicates that the
tunnel should bound to the destination address supplied in ta_daddr. The destination address must be reachable. The
IFTUN_ENCAP bit set in ifta_flags indicates that the tunnel's encapsulation limit should be set to the value supplied in
ifta_encap_lim. The encapsulation limit is valid only for IPv4-in-IPv6 and IPv6-in-IPv6 tunnels. Valid encapsulation
limit values are 0 through 255. Negative values indicate that no encapsulation limit is desired. The IFTUN_HOPLIMIT bit
set in ta_flags indicates that the tunnel's hop limit should be set to the value supplied in ifta_hop_limit. In the case
of IPv4-in-IPv4 and IPv6-in-IPv4 tunnels, the hop limit is placed in the IPv4 header's TTL field. In the case of
IPv4-in-IPv6 and IPv6-in-IPv6 tunnels, the hop limit is placed in the IPv6 header's hop limit field.
SIOCGTUNPARAM Get tunnel parameters. Valid fields are indicated by the returned value of ta_flags bitmask. The version of IP plumbed
above or below the tunnel may be determined by inspecting ta_upper and ta_lower by comparing the members against the
mutually exclusive defined values IFTAP_INVALID, IFTAP_IPV4, and IFTAP_IPV6.
Tunnels and DLPI
The tunnel module is a DLPI style 2 service provider. All M_PROTO and M_PCPROTO type messages are interpreted as DLPIprimitives. Valid
DLPI primitives are defined in <sys/dlpi.h>. Refer to dlpi(7P) for more information. An explicit DL_ATTACH_REQ message by the user is
required to associate the opened stream with a particular device (ppa). The ppa indicates the corresponding device instance (unit) num-
ber. The device is initialized on first attach and deinitialized (stopped) on last detach.
The values returned by the module in the DL_INFO_ACK primitive in response to the DL_INFO_REQ from the user are as follows:
o The maximum SDU is usually 4196 ("ip_max_mtu - size of IP header").
o The minimum SDU is 1.
o The dlsap address length is 0 for configured tunnels and non-zero for automatic tunnels.
o The MAC type is DL_OTHER.
o The sap length value is 0.
o The service mode is DL_CLDLS.
o No optional quality of service (QOS) support is included at present so the QOS fields are 0.
o The provider style is DL_STYLE2.
o The version is DL_VERSION_2.
o The broadcast address value is 0
Once in the DL_ATTACHED state, the user must send a DL_BIND_REQ to associate a particular SAP (Service Access Pointer) with the stream.
The tunneling module interprets the sap field within the DL_BIND_REQ as an IP "type" therefore the valid value for the sap field is
IP_DL_SAP.
Once in the DL_BOUND state, the user may transmit packets through the tunnel by sending DL_UNITDATA_REQ messages to the tunnel module.
Configured tunnels will encapsulate the packet with the appropriate IP header using the source and destination specified by tsrc and
tdst parameters of ifconfig(1M). The tunnel module will decapsulate received packets and route them to the first open and bound
stream having a sap, tsrc and tdst which matches the the configured information. Packets are routed to exactly one open stream and not
duplicated.
The module does not support additional primitives. DL_ERROR_ACK with the dl_error set to DL_UNSUPPORTED will be returned in the case
that an unsupported DLPI primitive is encountered.
SECURITY
A tunnel creates what appears to be a physical interface to IP. It can be "trusted" as a physical link only so far as the underlying secu-
rity protocols, if used, can be trusted. If the security associations (see ipsec(7P) are securely set up then the tunnel can be trusted in
that packets that come off the tunnel came from the peer specified in the tunnel destination. If this trust exists, per-interface IP for-
warding can be used to create a Virtual Private Network ("VPN"). See ip(7P).
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |SUNWcsr |
|Interface Stability |Evolving |
+-----------------------------+-----------------------------+
SEE ALSO
ifconfig(1M), attributes(5),ip(7P), ipsec(7P)
System Administration Guide: IP Services
Gilligan, R. and Nordmark, E., RFC 1933, Transition Mechanisms for IPv6 Hosts and Routers, The Internet Society, 1996.
Conta, A. and Deering, S. RFC 2473, Generic Packet Tunneling in IPv6 Specification, The Internet Society, 1998.
Carpenter, B and Moore, K. RVC 3056, Connection of IPv6 Domains via IPv4 Clouds, The Internet Society, 2001
SunOS 5.11 19 Aug 2004 tun(7M)