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