tun man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

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

NAME
     tun - network tunnel pseudo-device

SYNOPSIS
     pseudo-device tun

     #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 tunneling is supported; layer 3 tunneling is the
     default mode.  To enable layer 2 tunneling mode, where the tun interface
     simulates an Ethernet network interface, the link0 flag needs to be set
     with ifconfig(8) or by setting up a hostname.if(5) configuration file for
     netstart(8).  Note that setting or unsetting the link0 flag causes tun to
     lose any configuration settings, and that it is not advisable to use the
     flag with any other parameters.

     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 queued packets are
     discarded.	 If the device was created by opening /dev/tunN, it will be
     automatically destroyed.  Devices created via ifconfig(8) are only marked
     as not running and traffic will be dropped returning EHOSTDOWN.

     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.  Flags
	     given will be set; flags omitted will be cleared; flags not in
	     this list will not be changed even when given.  Flags default to
	     IFF_POINTOPOINT for layer 3 and to IFF_BROADCAST | IFF_MULTICAST
	     for layer 2 mode.	It is an error to set both IFF_POINTOPOINT and
	     IFF_BROADCAST.  type defaults to IFT_TUNNEL for layer 3 and
	     IFT_ETHER for layer 2 tunneling mode.  This sets the interface
	     media address header type.

     TUNSIFMODE int *flags
	     Set just the interface flags.  The same restrictions as for
	     TUNSIFINFO apply.

     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
     /dev/tun*

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

     [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
     inet(4), intro(4), netintro(4), hostname.if(5), ifconfig(8), netstart(8)

OpenBSD 4.9		      September 23, 2010		   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net