Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
tun(7M)				STREAMS	Modules			       tun(7M)

       tun, TUN	- tunneling STREAMS module



       tun  and	atun are STREAMS modules that implement	an IP-in-IP  tunneling
       mechanism.  IPv6-in-IPv4	and IPv4-in-IPv4 tunnels are supported.

       Tunnels are configured as point-to-point	interfaces.  Ipv4-in-Ipv4  al-
       lows  IPv4 packets to be	encapsulated within IPv4 packets. IPv6-in-IPv4
       tunnels	allow  IPv6  packets  to  be encapsulated within IPv4 packets.
       Both  the tunnel	source and the tunnel destination are required to con-
       figure these type of tunnels. Configured	     tunnels support  encapsu-
       lated  multicast	packets. See ifconfig(1M) for examples of these	tunnel

       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  com-
       patible	IPv6   source	address	 must match this address. IPv6 packets
       using this interface must have IPv4  compatible	source	 and  destina-
       tion  addresses.	 Automatic tunnels are not point-to-point, and they do
       not allow multicast packets to be sent. If the destination  of  an  au-
       tomatic tunnel is a router, the packets will not	be forwarded.

	  o  Network  startup  scripts	 look  at  /etc/hostname.ip.*  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 in-

	  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.

       The tunnel module is architected	to be plumbed  between	two  instances
       of IP.

       The  following  ioctl() calls may be used to configure a	 tunneling in-
       terface.	 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 {

       #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. */
		  /* These flags are set to indicate which members are valid */

       #define	  IFTUN_SRC		0x01
       #define	  IFTUN_DST		0x02
       #define	  IFTUN_SECURITY	0x04

       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).

	     Set   tunnel   parameters.	 This  ioctl()	allows	 the  tunnel's
	     source or destination address 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  des-
	     tination			       address must be reachable.

	     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	  mem-
	     bers  against  the	mutually  exclusive  defined  values IFTAP_IN-
	     VALID, IFTAP_IPV4,	and IFTAP_IPV6.	Currently, only	IFTAP_IPV4  is
	     supported,	as IP is currently  version 4.

   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)   number.
       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

	  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
	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.

       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  security
       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  forwarding
       can be used to create a Virtual Private Network ("VPN").	See ip(7P).

       See attributes(5)  for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcsr (32-bit)		   |
       |			     |SUNWcarx (64-bit)		   |
       |Interface Stability	     |Evolving			   |


       System Administration Guide: IP Services

       Gilligan, R. and	Nordmark, E., RFC 1933,	Transition Mechanisms for IPv6
       Hosts and Routers, The Internet Society,	1996.

SunOS 5.9			  28 Mar 2001			       tun(7M)


Want to link to this manual page? Use this URL:

home | help