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