share/man/man4/tun.4

   1 .\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
   2 .\" $FreeBSD$
   3 .\" Based on PR#2411
   4 .\"
   5 .Dd November 30, 2014
   6 .Dt TUN 4
   7 .Os
   8 .Sh NAME
   9 .Nm tun
  10 .Nd tunnel software network interface
  11 .Sh SYNOPSIS
  12 .Cd 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 A client program transfers IP (by default) packets to or from the
  39 .Nm
  40 .Dq control
  41 interface.
  42 The
  43 .Xr tap 4
  44 interface provides similar functionality at the Ethernet layer:
  45 a client will transfer Ethernet frames to or from a
  46 .Xr tap 4
  47 .Dq control
  48 interface.
  49 .Pp
  50 The network interfaces are named
  51 .Dq Li tun0 ,
  52 .Dq Li tun1 ,
  53 etc., one for each control device that has been opened.
  54 These network interfaces persist until the
  55 .Pa if_tun.ko
  56 module is unloaded, or until removed with the
  57 .Xr ifconfig 8
  58 command.
  59 .Pp
  60 .Nm
  61 devices are created using interface cloning.
  62 This is done using the
  63 .Dq ifconfig tun Ns Sy N No create
  64 command.
  65 This is the preferred method of creating
  66 .Nm
  67 devices.
  68 The same method allows removal of interfaces.
  69 For this, use the
  70 .Dq ifconfig tun Ns Sy N No destroy
  71 command.
  72 .Pp
  73 If the
  74 .Xr sysctl 8
  75 variable
  76 .Va net.link.tun.devfs_cloning
  77 is non-zero, the
  78 .Nm
  79 interface
  80 permits opens on the special control device
  81 .Pa /dev/tun .
  82 When this device is opened,
  83 .Nm
  84 will return a handle for the lowest unused
  85 .Nm
  86 device (use
  87 .Xr devname 3
  88 to determine which).
  89 .Pp
  90 .Bf Em
  91 Disabling the legacy devfs cloning functionality may break existing
  92 applications which use
  93 .Nm ,
  94 such as
  95 .Xr ppp 8
  96 and
  97 .Xr ssh 1 .
  98 It therefore defaults to being enabled until further notice.
  99 .Ef
 100 .Pp
 101 Control devices (once successfully opened) persist until
 102 .Pa if_tun.ko
 103 is unloaded in the same way that network interfaces persist (see above).
 104 .Pp
 105 Each interface supports the usual network-interface
 106 .Xr ioctl 2 Ns s ,
 107 such as
 108 .Dv SIOCAIFADDR
 109 and thus can be used with
 110 .Xr ifconfig 8
 111 like any other interface.
 112 At boot time, they are
 113 .Dv POINTOPOINT
 114 interfaces, but this can be changed; see the description of the control
 115 device, below.
 116 When the system chooses to transmit a packet on the
 117 network interface, the packet can be read from the control device
 118 (it appears as
 119 .Dq input
 120 there);
 121 writing a packet to the control device generates an input
 122 packet on the network interface, as if the (non-existent)
 123 hardware had just received it.
 124 .Pp
 125 The tunnel device
 126 .Pq Pa /dev/tun Ns Ar N
 127 is exclusive-open
 128 (it cannot be opened if it is already open).
 129 A
 130 .Xr read 2
 131 call will return an error
 132 .Pq Er EHOSTDOWN
 133 if the interface is not
 134 .Dq ready
 135 (which means that the control device is open and the interface's
 136 address has been set).
 137 .Pp
 138 Once the interface is ready,
 139 .Xr read 2
 140 will return a packet if one is available; if not, it will either block
 141 until one is or return
 142 .Er EWOULDBLOCK ,
 143 depending on whether non-blocking I/O has been enabled.
 144 If the packet is longer than is allowed for in the buffer passed to
 145 .Xr read 2 ,
 146 the extra data will be silently dropped.
 147 .Pp
 148 If the
 149 .Dv TUNSLMODE
 150 ioctl has been set, packets read from the control device will be prepended
 151 with the destination address as presented to the network interface output
 152 routine,
 153 .Fn tunoutput .
 154 The destination address is in
 155 .Vt struct sockaddr
 156 format.
 157 The actual length of the prepended address is in the member
 158 .Va sa_len .
 159 If the
 160 .Dv TUNSIFHEAD
 161 ioctl has been set, packets will be prepended with a four byte address
 162 family in network byte order.
 163 .Dv TUNSLMODE
 164 and
 165 .Dv TUNSIFHEAD
 166 are mutually exclusive.
 167 In any case, the packet data follows immediately.
 168 .Pp
 169 A
 170 .Xr write 2
 171 call passes a packet in to be
 172 .Dq received
 173 on the pseudo-interface.
 174 If the
 175 .Dv TUNSIFHEAD
 176 ioctl has been set, the address family must be prepended, otherwise the
 177 packet is assumed to be of type
 178 .Dv AF_INET .
 179 Each
 180 .Xr write 2
 181 call supplies exactly one packet; the packet length is taken from the
 182 amount of data provided to
 183 .Xr write 2
 184 (minus any supplied address family).
 185 Writes will not block; if the packet cannot be accepted for a
 186 transient reason
 187 (e.g., no buffer space available),
 188 it is silently dropped; if the reason is not transient
 189 (e.g., packet too large),
 190 an error is returned.
 191 .Pp
 192 The following
 193 .Xr ioctl 2
 194 calls are supported
 195 (defined in
 196 .In net/if_tun.h ) :
 197 .Bl -tag -width ".Dv TUNSIFMODE"
 198 .It Dv TUNSDEBUG
 199 The argument should be a pointer to an
 200 .Vt int ;
 201 this sets the internal debugging variable to that value.
 202 What, if anything, this variable controls is not documented here; see
 203 the source code.
 204 .It Dv TUNGDEBUG
 205 The argument should be a pointer to an
 206 .Vt int ;
 207 this stores the internal debugging variable's value into it.
 208 .It Dv TUNSIFINFO
 209 The argument should be a pointer to an
 210 .Vt struct tuninfo
 211 and allows setting the MTU, the type, and the baudrate of the tunnel
 212 device.
 213 The
 214 .Vt struct tuninfo
 215 is declared in
 216 .In net/if_tun.h .
 217 .Pp
 218 The use of this ioctl is restricted to the super-user.
 219 .It Dv TUNGIFINFO
 220 The argument should be a pointer to an
 221 .Vt struct tuninfo ,
 222 where the current MTU, type, and baudrate will be stored.
 223 .It Dv TUNSIFMODE
 224 The argument should be a pointer to an
 225 .Vt int ;
 226 its value must be either
 227 .Dv IFF_POINTOPOINT
 228 or
 229 .Dv IFF_BROADCAST
 230 and should have
 231 .Dv IFF_MULTICAST
 232 OR'd into the value if multicast support is required.
 233 The type of the corresponding
 234 .Dq Li tun Ns Ar N
 235 interface is set to the supplied type.
 236 If the value is outside the above range, an
 237 .Er EINVAL
 238 error is returned.
 239 The interface must be down at the time; if it is up, an
 240 .Er EBUSY
 241 error is returned.
 242 .It Dv TUNSLMODE
 243 The argument should be a pointer to an
 244 .Vt int ;
 245 a non-zero value turns off
 246 .Dq multi-af
 247 mode and turns on
 248 .Dq link-layer
 249 mode, causing packets read from the tunnel device to be prepended with
 250 the network destination address (see above).
 251 .It Dv TUNSIFPID
 252 Will set the pid owning the tunnel device to the current process's pid.
 253 .It Dv TUNSIFHEAD
 254 The argument should be a pointer to an
 255 .Vt int ;
 256 a non-zero value turns off
 257 .Dq link-layer
 258 mode, and enables
 259 .Dq multi-af
 260 mode, where every packet is preceded with a four byte address family.
 261 .It Dv TUNGIFHEAD
 262 The argument should be a pointer to an
 263 .Vt int ;
 264 the ioctl sets the value to one if the device is in
 265 .Dq multi-af
 266 mode, and zero otherwise.
 267 .It Dv FIONBIO
 268 Turn non-blocking I/O for reads off or on, according as the argument
 269 .Vt int Ns 's
 270 value is or is not zero.
 271 (Writes are always non-blocking.)
 272 .It Dv FIOASYNC
 273 Turn asynchronous I/O for reads
 274 (i.e., generation of
 275 .Dv SIGIO
 276 when data is available to be read)
 277 off or on, according as the argument
 278 .Vt int Ns 's
 279 value is or is not zero.
 280 .It Dv FIONREAD
 281 If any packets are queued to be read, store the size of the first one
 282 into the argument
 283 .Vt int ;
 284 otherwise, store zero.
 285 .It Dv TIOCSPGRP
 286 Set the process group to receive
 287 .Dv SIGIO
 288 signals, when asynchronous I/O is enabled, to the argument
 289 .Vt int
 290 value.
 291 .It Dv TIOCGPGRP
 292 Retrieve the process group value for
 293 .Dv SIGIO
 294 signals into the argument
 295 .Vt int
 296 value.
 297 .El
 298 .Pp
 299 The control device also supports
 300 .Xr select 2
 301 for read; selecting for write is pointless, and always succeeds, since
 302 writes are always non-blocking.
 303 .Pp
 304 On the last close of the data device, by default, the interface is
 305 brought down
 306 (as if with
 307 .Nm ifconfig Ar tunN Cm down ) .
 308 All queued packets are thrown away.
 309 If the interface is up when the data device is not open
 310 output packets are always thrown away rather than letting
 311 them pile up.
 312 .Sh SEE ALSO
 313 .Xr ioctl 2 ,
 314 .Xr read 2 ,
 315 .Xr select 2 ,
 316 .Xr write 2 ,
 317 .Xr devname 3 ,
 318 .Xr inet 4 ,
 319 .Xr intro 4 ,
 320 .Xr pty 4 ,
 321 .Xr tap 4 ,
 322 .Xr ifconfig 8
 323 .Sh AUTHORS
 324 This manual page was originally obtained from
 325 .Nx .