MirBSD manpage: tun(4)

TUN(4)                     BSD Programmer's Manual                      TUN(4)

NAME

     tun - network tunnel pseudo-device

SYNOPSIS

     pseudo-device tun [count]

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

DESCRIPTION

     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 tunnenling 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). In layer 2 mode the tun interface is simulat-
     ing 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 truncat-
     ed. Each write supplies exactly one packet. Each packet read or written
     is prefixed with a tunnel header consisting of a 4 byte network byte ord-
     er integer containing the address family in the case of layer 3 tunnel-
     ing. In layer 2 mode the 4 byte tunnel header is replaced with a 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)
             Can be used to 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 de-
             faults 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 inter-
             face media address header type.

     TUNSIFMODE int *flags
             Can be used to just set the interface flags.
     FIONBIO int *flag
             Can be used to set non-blocking I/O.
     FIOASYNC int *flag
             Can be used to 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
             Gets 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

     /dev/tun*

ERRORS

     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 avail-
                   able.

     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

     inet(4), intro(4), netintro(4), ifconfig(8)

HISTORY

     The ability to switch from a layer 3 interface (tunnel device) to a layer
     2 interface (ethertap device) has been added in MirBSD #8.

BUGS

     There is no way to set TUN_STAYUP.

     TUNSIFINFO does no checking on flags.

MirBSD #10-current              March 9, 2003                                2