tun(7M)




NAME

     tun, TUN - tunneling STREAMS module


SYNOPSIS

     strmod/tun

     strmod/atun


DESCRIPTION

     tun and atun 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  desti-
     nation are required to configure these type of tunnels. Con-
     figured   tunnels support  encapsulated  multicast  packets.
     See  ifconfig(1M)  for  examples  of these tunnel configura-
     tions.

     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 des-
     tination  of  an automatic tunnel is a router,  the  packets
     will not be forwarded.

        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 interface 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  tun-
     neling    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  tun-
           nel  should  bound to the destination address supplied
           in ta_daddr. The destination address  must  be  reach-
           able.  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 encapsu-
           lation 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)
     number. The  device is initialized on first attach and dein-
     itialized (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  (Ser-
     vice 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 mes-
     sages to the tunnel module. Configured tunnels will encapsu-
     late  the packet
      with the appropriate IP header using the source and  desti-
     nation
      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 informa-
     tion.  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 CONSIDERATIONS

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


ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsr (32-bit)            |
    |_____________________________|_____________________________|
    |                             | SUNWcarx (64-bit)           |
    |_____________________________|_____________________________|
    | 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  Mechan-
     isms 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.


Man(1) output converted with man2html