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