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