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