Unix/Linux Go Back    


NetBSD 6.1.5 - man page for tun (netbsd section 4)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


TUN(4)				   BSD Kernel Interfaces Manual 			   TUN(4)

NAME
     tun -- tunnel software network interface

SYNOPSIS
     pseudo-device tun

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

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

     To use a tun device, the administrator must first create the interface.  This can be done by
     using the ifconfig(8) create command, or via the SIOCIFCREATE ioctl.  An open() call on
     /dev/tunN, will also create a network interface with the same unit number of that device if
     it doesn't exist yet.

     The network interfaces should be named tun0, tun1, etc.  Each interface supports the usual
     network-interface ioctl(2)s, such as SIOCSIFADDR and SIOCSIFNETMASK, 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 con-
     trol device (it appears there as ``output''); writing a packet to the control device gener-
     ates an input packet on the network interface, as if the (non-existent) hardware had just
     received it.

     The tunnel device, normally /dev/tunN, is exclusive-open (it cannot be opened if it is
     already open) and is restricted to the super-user (regardless of file system permissions).
     A read() call will return an error (EHOSTDOWN) if the interface is not ``ready'' (which
     means that the interface address has not been set).  Once the interface is ready, read()
     will return a packet if one is available; if not, it will either block until one is or
     return EAGAIN, depending on whether non-blocking I/O has been enabled.  If the packet is
     longer than is allowed for in the buffer passed to read(), the extra data will be silently
     dropped.

     Packets can be optionally 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'.  The packet
     data follows immediately.	A write(2) call passes a packet in to be ``received'' on the
     pseudo-interface.	Each write() call supplies exactly one packet; the packet length is taken
     from the amount of data provided to write().  Writes will not block; if the packet cannot be
     accepted for a transient 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.  If
     ``link-layer mode'' is on (see TUNSLMODE below), the actual packet data must be preceded by
     a 'struct sockaddr'.  The driver currently only inspects the 'sa_family' field.  The follow-
     ing ioctl(2) calls are supported (defined in <net/if_tun.h>):

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

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

     TUNSIFMODE  The argument should be a pointer to an int; its value must be either
		 IFF_POINTOPOINT or IFF_BROADCAST (optionally IFF_MULTICAST may be or'ed into the
		 value).  The type of the corresponding tunn interface is set to the supplied
		 type.	If the value is anything else, an EINVAL error occurs.	The interface
		 must be down at the time; if it is up, an EBUSY error occurs.

     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, causing packets read from
		 the tunnel device to be prepended with network destination address.

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

     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 pre-
		 ceded with a four byte address family.

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

     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 argument int's value is or
		 isn't 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 asynchronous I/O is
		 enabled, to the argument int value.

     TIOCGPGRP	 Retrieve the process group value for SIGIO signals into the argument 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
     inet(4), intro(4)

HISTORY
     IPv6 support comes mostly from FreeBSD and was added in NetBSD 4.0 by
     Rui Paulo <rpaulo@NetBSD.org>.

BSD					  April 8, 2006 				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:10 AM.