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 29, 2017
   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 and the baudrate of the tunnel
 212 device.
 213 The type must be the same as returned by
 214 .Dv TUNGIFINFO
 215 or set to
 216 .Dv IFT_PPP
 217 else the
 218 .Xr ioctl 2
 219 call will fail.
 220 The
 221 .Vt struct tuninfo
 222 is declared in
 223 .In net/if_tun.h .
 224 .Pp
 225 The use of this ioctl is restricted to the super-user.
 226 .It Dv TUNGIFINFO
 227 The argument should be a pointer to an
 228 .Vt struct tuninfo ,
 229 where the current MTU, type, and baudrate will be stored.
 230 .It Dv TUNSIFMODE
 231 The argument should be a pointer to an
 232 .Vt int ;
 233 its value must be either
 234 .Dv IFF_POINTOPOINT
 235 or
 236 .Dv IFF_BROADCAST
 237 and should have
 238 .Dv IFF_MULTICAST
 239 OR'd into the value if multicast support is required.
 240 The type of the corresponding
 241 .Dq Li tun Ns Ar N
 242 interface is set to the supplied type.
 243 If the value is outside the above range, an
 244 .Er EINVAL
 245 error is returned.
 246 The interface must be down at the time; if it is up, an
 247 .Er EBUSY
 248 error is returned.
 249 .It Dv TUNSLMODE
 250 The argument should be a pointer to an
 251 .Vt int ;
 252 a non-zero value turns off
 253 .Dq multi-af
 254 mode and turns on
 255 .Dq link-layer
 256 mode, causing packets read from the tunnel device to be prepended with
 257 the network destination address (see above).
 258 .It Dv TUNSIFPID
 259 Will set the pid owning the tunnel device to the current process's pid.
 260 .It Dv TUNSIFHEAD
 261 The argument should be a pointer to an
 262 .Vt int ;
 263 a non-zero value turns off
 264 .Dq link-layer
 265 mode, and enables
 266 .Dq multi-af
 267 mode, where every packet is preceded with a four byte address family.
 268 .It Dv TUNGIFHEAD
 269 The argument should be a pointer to an
 270 .Vt int ;
 271 the ioctl sets the value to one if the device is in
 272 .Dq multi-af
 273 mode, and zero otherwise.
 274 .It Dv FIONBIO
 275 Turn non-blocking I/O for reads off or on, according as the argument
 276 .Vt int Ns 's
 277 value is or is not zero.
 278 (Writes are always non-blocking.)
 279 .It Dv FIOASYNC
 280 Turn asynchronous I/O for reads
 281 (i.e., generation of
 282 .Dv SIGIO
 283 when data is available to be read)
 284 off or on, according as the argument
 285 .Vt int Ns 's
 286 value is or is not zero.
 287 .It Dv FIONREAD
 288 If any packets are queued to be read, store the size of the first one
 289 into the argument
 290 .Vt int ;
 291 otherwise, store zero.
 292 .It Dv TIOCSPGRP
 293 Set the process group to receive
 294 .Dv SIGIO
 295 signals, when asynchronous I/O is enabled, to the argument
 296 .Vt int
 297 value.
 298 .It Dv TIOCGPGRP
 299 Retrieve the process group value for
 300 .Dv SIGIO
 301 signals into the argument
 302 .Vt int
 303 value.
 304 .El
 305 .Pp
 306 The control device also supports
 307 .Xr select 2
 308 for read; selecting for write is pointless, and always succeeds, since
 309 writes are always non-blocking.
 310 .Pp
 311 On the last close of the data device, by default, the interface is
 312 brought down
 313 (as if with
 314 .Nm ifconfig Ar tunN Cm down ) .
 315 All queued packets are thrown away.
 316 If the interface is up when the data device is not open
 317 output packets are always thrown away rather than letting
 318 them pile up.
 319 .Sh SEE ALSO
 320 .Xr ioctl 2 ,
 321 .Xr read 2 ,
 322 .Xr select 2 ,
 323 .Xr write 2 ,
 324 .Xr devname 3 ,
 325 .Xr inet 4 ,
 326 .Xr intro 4 ,
 327 .Xr pty 4 ,
 328 .Xr tap 4 ,
 329 .Xr ifconfig 8
 330 .Sh AUTHORS
 331 This manual page was originally obtained from
 332 .Nx .