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