share/man/man4/tun.4

   1 .\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
   2 .\" $FreeBSD: src/share/man/man4/tun.4,v 1.9.2.4 2001/08/17 13:08:39 ru Exp $
   3 .\" $DragonFly: src/share/man/man4/tun.4,v 1.3 2006/05/26 19:39:39 swildner Exp $
   4 .\" Based on PR#2411
   5 .\"
   6 .Dd August 6, 2009
   7 .Dt TUN 4
   8 .Os
   9 .Sh NAME
  10 .Nm tun
  11 .Nd tunnel software network interface
  12 .Sh SYNOPSIS
  13 .Cd pseudo-device tun
  14 .Sh DESCRIPTION
  15 The
  16 .Nm
  17 interface is a software loopback mechanism that can be loosely
  18 described as the network interface analog of the
  19 .Xr pty 4 ,
  20 that is,
  21 .Nm
  22 does for network interfaces what the
  23 .Xr pty 4
  24 driver does for terminals.
  25 .Pp
  26 The
  27 .Nm
  28 driver, like the
  29 .Xr pty 4
  30 driver, provides two interfaces: an interface like the usual facility
  31 it is simulating
  32 (a network interface in the case of
  33 .Nm ,
  34 or a terminal for
  35 .Xr pty 4 ) ,
  36 and a character-special device
  37 .Dq control
  38 interface.
  39 .Pp
  40 The network interfaces are named
  41 .Dq Li tun0 ,
  42 .Dq Li tun1 ,
  43 etc, and each one supports the usual network-interface
  44 .Xr ioctl 2 Ns s ,
  45 such as
  46 .Dv SIOCSIFADDR
  47 and
  48 .Dv SIOCSIFNETMASK ,
  49 and thus can be used with
  50 .Xr ifconfig 8
  51 like any other interface.
  52 At boot time, they are
  53 .Dv POINTOPOINT
  54 interfaces, but this can be changed; see the description of the control
  55 device, below.
  56 When the system chooses to transmit a packet on the
  57 network interface, the packet can be read from the control device
  58 (it appears as
  59 .Dq input
  60 there);
  61 writing a packet to the control device generates an input
  62 packet on the network interface, as if the (non\-existent)
  63 hardware had just received it.
  64 .Pp
  65 The tunnel device, normally
  66 .Pa /dev/tun Ns Ar N ,
  67 is exclusive-open
  68 (it cannot be opened if it is already open)
  69 and is restricted to the super-user.
  70 A
  71 .Xr read 2
  72 call will return an error
  73 .Pq Er EHOSTDOWN
  74 if the interface is not
  75 .Dq ready
  76 (which means that the control device is open and the interface's
  77 address has been set).
  78 .Pp
  79 Once the interface is ready,
  80 .Xr read 2
  81 will return a packet if one is available; if not, it will either block
  82 until one is or return
  83 .Er EWOULDBLOCK ,
  84 depending on whether non-blocking I/O has been enabled.
  85 If the packet is longer than is allowed for in the buffer passed to
  86 .Xr read 2 ,
  87 the extra data will be silently dropped.
  88 .Pp
  89 Packets can be optionally prepended with the destination address as presented
  90 to the network interface output routine,
  91 .Fn tunoutput .
  92 The destination address is in
  93 .Vt struct sockaddr
  94 format.
  95 The actual length of the prepended address is in the member
  96 .Va sa_len .
  97 The packet data follows immediately.
  98 .Pp
  99 A
 100 .Xr write 2
 101 call passes a packet in to be
 102 .Dq received
 103 on the pseudo-interface.
 104 Each
 105 .Xr write 2
 106 call supplies exactly one packet; the packet length is taken from the
 107 amount of data provided to
 108 .Xr write 2 .
 109 Writes will not block; if the packet cannot be accepted for a
 110 transient reason
 111 (e.g., no buffer space available),
 112 it is silently dropped; if the reason is not transient
 113 (e.g., packet too large),
 114 an error is returned.
 115 If
 116 .Dq link-layer mode
 117 is on
 118 (see
 119 .Dv TUNSLMODE
 120 below),
 121 the actual packet data must be preceded by a
 122 .Vt struct sockaddr .
 123 The driver currently only inspects the
 124 .Va sa_family
 125 field.
 126 .Pp
 127 The following
 128 .Xr ioctl 2
 129 calls are supported
 130 (defined in
 131 .In net/tun/if_tun.h ) :
 132 .Bl -tag -width ".Dv TUNSIFMODE"
 133 .It Dv TUNSDEBUG
 134 The argument should be a pointer to an
 135 .Vt int ;
 136 this sets the internal debugging variable to that value.
 137 What, if anything, this variable controls is not documented here; see
 138 the source code.
 139 .It Dv TUNGDEBUG
 140 The argument should be a pointer to an
 141 .Vt int ;
 142 this stores the internal debugging variable's value into it.
 143 .It Dv TUNSIFINFO
 144 The argument should be a pointer to an
 145 .Vt struct tuninfo
 146 and allows setting the MTU, the type, and the baudrate of the tunnel
 147 device.
 148 The
 149 .Vt struct tuninfo
 150 is declared in
 151 .In net/tun/if_tun.h .
 152 .It Dv TUNGIFINFO
 153 The argument should be a pointer to an
 154 .Vt struct tuninfo ,
 155 where the current MTU, type, and baudrate will be stored.
 156 .It Dv TUNSIFMODE
 157 The argument should be a pointer to an
 158 .Vt int ;
 159 its value must be either
 160 .Dv IFF_POINTOPOINT
 161 or
 162 .Dv IFF_BROADCAST .
 163 The type of the corresponding
 164 .Dq Li tun Ns Ar N
 165 interface is set to the supplied type.
 166 If the value is anything else, an
 167 .Er EINVAL
 168 error occurs.
 169 The interface must be down at the time; if it is up, an
 170 .Er EBUSY
 171 error occurs.
 172 .It Dv TUNSLMODE
 173 The argument should be a pointer to an
 174 .Vt int ;
 175 a non-zero value turns on
 176 .Dq link-layer
 177 mode, causing packets read from the tunnel device to be prepended with
 178 network destination address.
 179 .It Dv TUNSIFPID
 180 Will set the pid owning the tunnel device to the current process's pid.
 181 .It Dv TUNSIFHEAD
 182 The argument should be a pointer to an
 183 .Vt int ;
 184 a non-zero value turns off
 185 .Dq link-layer
 186 mode, and enables
 187 .Dq multi-af
 188 mode, where every packet is preceded with a four byte address family.
 189 .It Dv TUNGIFHEAD
 190 The argument should be a pointer to an
 191 .Vt int ;
 192 this stores one if the device is in
 193 .Dq multi-af
 194 mode, and zero otherwise in it.
 195 .It Dv FIONBIO
 196 Turn non-blocking I/O for reads off or on, according as the argument
 197 .Vt int Ns 's
 198 value is or isn't zero.
 199 (Writes are always non-blocking.)
 200 .It Dv FIOASYNC
 201 Turn asynchronous I/O for reads
 202 (i.e., generation of
 203 .Dv SIGIO
 204 when data is available to be read)
 205 off or on, according as the argument
 206 .Vt int Ns 's
 207 value is or isn't zero.
 208 .It Dv FIONREAD
 209 If any packets are queued to be read, store the size of the first one
 210 into the argument
 211 .Vt int ;
 212 otherwise, store zero.
 213 .It Dv TIOCSPGRP
 214 Set the process group to receive
 215 .Dv SIGIO
 216 signals, when asynchronous I/O is enabled, to the argument
 217 .Vt int
 218 value.
 219 .It Dv TIOCGPGRP
 220 Retrieve the process group value for
 221 .Dv SIGIO
 222 signals into the argument
 223 .Vt int
 224 value.
 225 .El
 226 .Pp
 227 The control device also supports
 228 .Xr select 2
 229 for read; selecting for write is pointless, and always succeeds, since
 230 writes are always non-blocking.
 231 .Pp
 232 On the last close of the data device, by default, the interface is
 233 brought down
 234 (as if with
 235 .Nm ifconfig Ar tunN Cm down ) .
 236 All queued packets are thrown away.
 237 If the interface is up when the data device is not open
 238 output packets are always thrown away rather than letting
 239 them pile up.
 240 .Sh SEE ALSO
 241 .Xr inet 4 ,
 242 .Xr intro 4
 243 .Sh AUTHORS
 244 This manual page was originally obtained from
 245 .Nx .