NAME    [Toc]    [Back]

     tun - network tunnel pseudo-device

SYNOPSIS    [Toc]    [Back]

     pseudo-device tun [count]

     #include <sys/types.h>
     #include <net/if_tun.h>

DESCRIPTION    [Toc]    [Back]

     The tun driver provides a network  interface  pseudo-device.
Packets sent
     to this interface can be read by a userland process and processed as desired.
  Packets written by the userland process are injected
back into
     the kernel networking subsystem.

     A tun interface can be created at runtime using the ifconfig
tunN create
     command  or  by  opening  the   character   special   device
/dev/tunN.

     Both  layer  3  and layer 2 tunneling is supported.  Layer 3
tunneling is
     the default mode; to enable layer 2 tunneling mode the link0
flag needs
     to  be  set  with  ifconfig(8),  or  by  setting  up a hostname.if(5) configuration
 file for netstart(8).  In layer 2 mode the  tun  interface is simulating
 an Ethernet network interface.

     Each  device  has  the exclusive open property; it cannot be
opened if it is
     already open and in use by another process.  Each  read  returns at most
     one  packet;  if  insufficient buffer space is provided, the
packet is truncated.
  Each write supplies exactly one packet.  Each packet
read or
     written  is  prefixed  with  a tunnel header consisting of a
4-byte network
     byte order integer containing the address family in the case
of layer 3
     tunneling.   In layer 2 mode the 4-byte tunnel header is replaced with an
     Ethernet header.  On the last close of the device, all packets are discarded,
  the  device  is marked down, and all routes via the
device are removed.


     Writes never block.  If the  protocol  queue  is  full,  the
packet is
     dropped,  a  ``collision''  is  counted,  and ENOBUFS is returned.

     In addition to the usual network  interface  ioctl  commands
described in
     netintro(4),  the  following  special  commands  defined  in
<net/if_tun.h> are
     supported:

     TUNGIFINFO struct tuninfo *
     TUNSIFINFO struct tuninfo *
             Get or set the interface characteristics.

             /* iface info */
             struct tuninfo {
                     u_int   mtu;
                     u_short type;
                     u_short flags;
                     u_int   baudrate;
             };

             flags sets the interface flags, and can include  one
or more of
             IFF_UP,  IFF_POINTOPOINT,  IFF_MULTICAST, IFF_BROADCAST.  It defaults
 to IFF_POINTOPOINT.  It is an  error  to  set
both
             IFF_POINTOPOINT and IFF_BROADCAST.  type defaults to
             IFT_PROPVIRTUAL but can be  set  to  IFT_PPP.   This
sets the interface
 media address header type.

     TUNSIFMODE int *flags
             Set just the interface flags.

     FIONBIO int *flag
             Set non-blocking I/O.

     FIOASYNC int *flag
             Cause  signal  SIGIO to be sent when a packet can be
read.

     TIOCSPGRP int *pgrp
     TIOCGPGRP int *pgrp
             Get or set the process group to which signals  might
be sent via
             FIOASYNC.

     FIONREAD int *count
             Get  the  byte count of the next packet available to
be read.

     SIOCGIFADDR struct ether_addr *addr
     SIOCSIFADDR struct ether_addr *addr
             Get or set the Ethernet address  of  the  device  in
layer 2 mode.

FILES    [Toc]    [Back]

     /dev/tun*

ERRORS    [Toc]    [Back]

     If open fails, errno(2) may be set to one of:

     [EPERM]       Only the superuser may open the device.

     [ENXIO]       Not that many devices configured.

     [EBUSY]       Device was already open.

     If a write(2) call fails, errno(2) is set to one of:

     [EMSGSIZE]     The  packet  supplied  was  too  small or too
large.  The maximum
 sized packet allowed  is  currently  16384
bytes.

     [ENOBUFS]     There were no mbufs, or the queue for the outgoing protocol
                   is full.

     [EAFNOSUPPORT]
                   The address family  specified  in  the  tunnel
header was not
                   recognized.

     Ioctl commands may fail with:

     [EINVAL]        Attempt  to  set  both  IFF_POINTOPOINT  and
IFF_BROADCAST with
                   TUNSIFMODE or using SIOCGIFADDR or SIOCSIFADDR
in layer 3
                   mode.

     [ENOTTY]      Unrecognized ioctl command.

     A read(2) call may fail because of:

     [EHOSTDOWN]   The device is not ready.  The device must have
an inet(4)
                   interface address assigned to it, such as  via
SIOCSIFADDR.

     [EWOULDBLOCK]
                   Non-blocking  I/O  was selected and no packets
were available.


     An attempt to send a packet out via the interface  may  fail
with:

     [EHOSTDOWN]   The device is not ready.  The device must have
an inet(4)
                   interface address assigned to it, such as  via
SIOCSIFADDR.

SEE ALSO    [Toc]    [Back]

     inet(4), intro(4), netintro(4), hostname.if(5), ifconfig(8),
netstart(8)

BUGS    [Toc]    [Back]

     There is no way to set TUN_STAYUP.

     TUNSIFINFO does no checking on flags.

OpenBSD     3.6                           March      9,      2003