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

NAME
     ttuunn - Tunnel Network Interface

SYNOPSIS
     ppsseeuuddoo-ddeevviiccee ttuunn 44

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

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

     The network interfaces are named ttuunn0, ttuunn1, etc, as many in all as the
     count figure given on the ppsseeuuddoo-ddeevviiccee line.  Each one 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 control device (it appears as ``input'' there);
     writing a packet to the control device generates an input packet on the
     network interface, as if the (nonexistent) hardware had just received it.

     There are two control interfaces.  The data interface, normally
     /dev/tunNN, is exclusive-open (it cannot be opened if it is already open),
     is normally restricted to the super-user, and can ``transmit'' and
     ``receive'' packets.  The control interface, normally /dev/tuncNN, cannot
     send and receive packets, but can be opened by many processes at once; it
     is intended for status queries and changes (many of which can also be
     implemented with iiooccttll() calls on the data interface).  There are a num-
     ber of status bits that can be set or cleared via the control interfaces;
     they are mentioned below where applicable, and they are all summarized in
     the discussions of the control interfaces.

   The data interface     The data interface supports read(2), write(2), and ioctl(2) calls to,
     respectively, collect ``output'' packets, generate ``input'' packets, and
     perform control functions.  As mentioned above, this interface is exclu-
     sive-open; if the SUONLY bit is set (which it is by default), it cannot
     be opened at all except by the super-user.  By default, a rreeaadd() 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); if preferred, the RRWAIT bit can be set, in which case a
     rreeaadd() call will block (even if non-blocking I/O has been enabled) until
     the interface is ready.  Once the interface is ready, rreeaadd() will return
     a packet if one is available; if not, it will either block until one is
     or return EWOULDBLOCK, depending on whether non-blocking I/O has been
     enabled.  If the packet is longer than is allowed for in the buffer
     passed to rreeaadd(), the extra data will be silently dropped.

     The first byte of data will always be the address family (eg, AFINET) of
     the packet.  By default, the packet data follows immediately, but if the
     PREPADDR bit is set, the address to which the packet is to be sent is
     placed after the address family byte and before the packet data.  The
     size and layout of the address depends on the address family; for
     AFINET, for example, it is a struct inaddr.  A write(2) call passes a
     packet in to be ``received'' on the pseudo-interface.  Each wwrriittee() call
     supplies exactly one packet; the packet length is taken from the amount
     of data provided to wwrriittee().  The first byte must be the address family
     of the packet, much as in packets returned by rreeaadd(); the packet data
     always follows immediately.  A large number of ioctl(2) calls are also
     supported.  They are defined in .

     TUNSDEBUG     The argument should be a pointer to an int; this sets the
                   internal debugging variable to that value.  What, if any-
                   thing, this variable controls is not documented 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.

     TUNSMODE      The argument should be a pointer to an int; its value must
                   be IFFPOINTOPOINT or IFFBROADCAST.  The type of the cor-
                   responding tunnn 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.
     The data control device also supports select(2) for read; selecting for
     write is pointless, and always succeeds, since writes are always non-
     blocking (if the packet cannot be accepted for a transient reason (eg, no
     buffer space available), it is silently dropped; if the reason is not
     transient (eg, packet too large), an error is returned).

     On the last close of the data device, by default, the interface is
     brought down (as if with ``ifconfig tunnn ddoowwnn''); if the STAYUP bit is
     set, this is not done.  In either case, all queued packets are thrown
     away.  (If the interface is up when the data device is not open, either
     because of STAYUP or because it was explicitly brought up, output packets
     are always thrown away rather than letting them pile up.)

   The control interface
     The alternative control interface is a text-based interface designed for
     shell-script or human use; it allows control of many of the things that
     can be done with iiooccttll() calls on the data interface, and a few more as
     well.

     rreeaadd()s on the control interface always return a single line of text (or
     just the beginning of the line, if the buffer passed to read(2) was too
     small to take the whole line).  The line contains items in the general
     format ``item=value'', where item is a keyword and value is a value
     appropriate to the keyword.  This line is intended for human use; pro-
     grams should use the iiooccttll() interface.  Here is an actual example (bro-
     ken because of width restrictions):

     unit=0 flags=(open,inited,!rcoll,iaset,!dstaddr,!rwait,!async,
     !nbio,!brdaddr,prepaddr,stayup,suonly,rrwait) type=broadcast
     mtu=1500 coll=0 ipkts=0/0 opkts=0/0 pgrp=0

     Note that the current file offset is ignored for reads, so using a tool
     like cat(1) will result in infinite output.  Use something more like
     ``head -1'' for command-line use.  It is possible to select(2) for read-
     ing on this device, which will indicate that the device is readable when-
     ever the state is changed.

     Writes to the control interface are interpreted as modifications to the
     state.  Each wwrriittee() call is treated separately.  The data written is
     broken at whitespace (blanks, tabs, newlines); each resulting fragment
     has its first character examined.  If this character is a `+' or `-', the
     rest of the fragment is taken as a flag name, and the flag is turned on
     (for `+') or off (for `-').  (Flag names are as generated on reads; they
     are the same as the TUNxxx constants, with the leading TUN removed and
     the rest lowercased.)  If the first character is `t', the second charac-
     ter must be `b' or `p', and the interface type is set to IFFBROADCAST or
     IFFPOINTOPOINT, respectively.  If the first character is `g' or `m', the
     rest of the fragment is taken as a number in decimal (possibly with a
     leading - sign) and the result is taken as a new process group, for `g'
     or MTU, for `m'.  (The MTU must not be less than 1; attempts to set it so
     return EIO.)

     This interface is useful for command-line reconfiguration, such as set-
     ting the interface type at boot time, with

SEE ALSO
     intro(4), inet(4)

BUGS
     The SUONLY bit is a botch, especially since the control interface, which
     is never restricted by the kernel, can change it.  Access control really
     should be handled by the permission bits on the /dev entries for the data
     and control devices; this bit is a historical artifact.

     The process-group values for SIGIO signals should be checked; as it
     stands, the driver can be used (by anyone who can open the control or
     data device) to send any desired signal to an arbitrary process or
     process group.  (Until this is fixed, you should be careful to set the
     permisison bits to allow only root to open the control device, and either
     do the same for the data device or leave the SUONLY bit set.)

OpenBSD 1.2                     March 10, 1996                     OpenBSD 1.2