home | help 
TUN(4)			     Kernel Interfaces Manual			  TUN(4)

NAME
     tun -- tunnel software network interface

SYNOPSIS
     device tun

DESCRIPTION
     The  tun interface is a software loopback mechanism that can be loosely de-
     scribed as the network interface analog of the pty(4), that  is,  tun  does
     for network interfaces what the pty(4) driver does for terminals.

     The  tun driver, like the pty(4) driver, provides two interfaces: an inter-
     face like the usual facility it is simulating (a network interface  in  the
     case  of  tun,  or  a  terminal for pty(4)), and a character-special device
     "control" interface.

     The network interfaces are named "tun0", "tun1", etc., one for each control
     device that has been opened.  These network interfaces  persist  until  the
     if_tun.ko	module	is  unloaded, or until removed with the ifconfig(8) com-
     mand.

     tun devices are created using interface cloning.  This is	done  using  the
     "ifconfig	tunN  create" command.	This is the preferred method of creating
     tun devices.  The same method allows removal of interfaces.  For this,  use
     the "ifconfig tunN destroy" command.

     If  the  sysctl(8) variable net.link.tun.devfs_cloning is non-zero, the tun
     interface permits opens on the special control device /dev/tun.  When  this
     device is opened, tun will return a handle for the lowest unused tun device
     (use devname(3) to determine which).

     Disabling	the legacy devfs cloning functionality may break existing appli-
     cations which use tun, such as ppp(8) and ssh(1).	It therefore defaults to
     being enabled until further notice.

     Control devices (once successfully opened) persist until if_tun.ko  is  un-
     loaded in the same way that network interfaces persist (see above).

     Each  interface  supports	the  usual  network-interface ioctl(2)s, such as
     SIOCAIFADDR and thus can be used with ifconfig(8) like any other interface.
     At boot time, they are POINTOPOINT interfaces, but this can be changed; see
     the description of the control device, below.  When the system  chooses  to
     transmit a packet on the network interface, the packet can be read from the
     control  device (it appears as "input" there); writing a packet to the con-
     trol device generates an input packet on the network interface, as  if  the
     (non-existent) hardware had just received it.

     The  tunnel device (/dev/tunN) is exclusive-open (it cannot be opened if it
     is already open).	A read(2) call will return an error (EHOSTDOWN)  if  the
     interface	is  not "ready" (which means that the control device is open and
     the interface's address has been set).

     Once the interface is ready, read(2) will return a packet if one is  avail-
     able;  if not, it will either block until one is or return EWOULDBLOCK, de-
     pending on whether non-blocking I/O has been enabled.   If  the  packet  is
     longer  than is allowed for in the buffer passed to read(2), the extra data
     will be silently dropped.

     If the TUNSLMODE ioctl has been set, packets read from the  control  device
     will  be prepended with the destination address as presented to the network
     interface output routine,	tunoutput().   The  destination  address  is  in
     struct  sockaddr  format.	The actual length of the prepended address is in
     the member sa_len.  If the TUNSIFHEAD ioctl has been set, packets	will  be
     prepended with a four byte address family in network byte order.  TUNSLMODE
     and  TUNSIFHEAD  are mutually exclusive.  In any case, the packet data fol-
     lows immediately.

     A write(2) call passes a packet in to be "received"  on  the  pseudo-inter-
     face.   If  the  TUNSIFHEAD  ioctl has been set, the address family must be
     prepended, otherwise the packet is assumed to be  of  type  AF_INET.   Each
     write(2)  call supplies exactly one packet; the packet length is taken from
     the amount of data provided to write(2) (minus any  supplied  address  fam-
     ily).   Writes will not block; if the packet cannot be accepted for a tran-
     sient reason (e.g., no buffer space available), it is silently dropped;  if
     the reason is not transient (e.g., packet too large), an error is returned.

     The following ioctl(2) calls are supported (defined in <net/if_tun.h>):

     TUNSDEBUG	 The  argument	should be a pointer to an int; this sets the in-
		 ternal debugging variable to that value.   What,  if  anything,
		 this  variable  controls is not documented here; see the source
		 code.

     TUNGDEBUG	 The argument should be a pointer to an int; this stores the in-
		 ternal debugging variable's value into it.

     TUNSIFINFO  The argument should be a pointer to an struct tuninfo	and  al-
		 lows  setting the MTU, the type, and the baudrate of the tunnel
		 device.  The struct tuninfo is declared in <net/if_tun.h>.

		 The use of this ioctl is restricted to the super-user.

     TUNGIFINFO  The argument should be a pointer to an  struct  tuninfo,  where
		 the current MTU, type, and baudrate will be stored.

     TUNSIFMODE  The  argument	should be a pointer to an int; its value must be
		 either  IFF_POINTOPOINT  or  IFF_BROADCAST  and   should   have
		 IFF_MULTICAST	OR'd  into the value if multicast support is re-
		 quired.  The type of the corresponding "tunN" interface is  set
		 to the supplied type.	If the value is outside the above range,
		 an EINVAL error is returned.  The interface must be down at the
		 time; if it is up, an EBUSY error is returned.

     TUNSLMODE	 The  argument	should	be a pointer to an int; a non-zero value
		 turns off "multi-af" mode and turns on "link-layer" mode, caus-
		 ing packets read from the tunnel device to  be  prepended  with
		 the network destination address (see above).

     TUNSIFPID	 Will  set  the  pid  owning  the  tunnel  device to the current
		 process's pid.

     TUNSIFHEAD  The argument should be a pointer to an int;  a  non-zero  value
		 turns off "link-layer" mode, and enables "multi-af" mode, where
		 every packet is preceded with a four byte address family.

     TUNGIFHEAD  The  argument should be a pointer to an int; the ioctl sets the
		 value to one if the device is in "multi-af" mode, and zero oth-
		 erwise.

     FIONBIO	 Turn non-blocking I/O for reads off or on, according as the ar-
		 gument int's value is or is not zero.	(Writes are always  non-
		 blocking.)

     FIOASYNC	 Turn asynchronous I/O for reads (i.e., generation of SIGIO when
		 data is available to be read) off or on, according as the argu-
		 ment int's value is or is not zero.

     FIONREAD	 If  any  packets  are	queued to be read, store the size of the
		 first one into the argument int; otherwise, store zero.

     TIOCSPGRP	 Set the process group to receive SIGIO signals, when  asynchro-
		 nous I/O is enabled, to the argument int value.

     TIOCGPGRP	 Retrieve the process group value for SIGIO signals into the ar-
		 gument int value.

     The control device also supports select(2) for read; selecting for write is
     pointless, and always succeeds, since writes are always non-blocking.

     On  the last close of the data device, by default, the interface is brought
     down (as if with ifconfig tunN down).  All queued packets are thrown  away.
     If  the interface is up when the data device is not open output packets are
     always thrown away rather than letting them pile up.

SEE ALSO
     ioctl(2), read(2),  select(2),  write(2),	devname(3),  inet(4),  intro(4),
     pty(4), ifconfig(8)

AUTHORS
     This manual page was originally obtained from NetBSD.

FreeBSD 7.1			February 4, 2007			  TUN(4)
home | help