bsd/man/man4/tun.4

   1 .\"     $OpenBSD: tun.4,v 1.2 1996/12/16 16:08:52 deraadt Exp $
   2 .Dd March 10, 1996
   3 .Dt TUN 4
   4 .Os OpenBSD 1.2
   5 .Sh NAME
   6 .Nm tun
   7 .Nd Tunnel Network Interface
   8 .Sh SYNOPSIS
   9 .Cd "pseudo-device tun 4"
  10 .Sh DESCRIPTION
  11 The
  12 .Nm tun
  13 interface is a software loopback mechanism that can be loosely
  14 described as the network interface analog of the
  15 .Xr pty 4 ,
  16 that is,
  17 .Nm tun
  18 does for network interfaces what the
  19 .Nm pty
  20 driver does for terminals.
  21 .Pp
  22 The
  23 .Nm tun
  24 driver, like the
  25 .Nm pty
  26 driver, provides two interfaces: an interface like the usual facility
  27 it is simulating (a network interface in the case of
  28 .Nm tun ,
  29 or a terinal for
  30 .Nm pty ) ,
  31 and a character-special device
  32 .Dq control
  33 interface.
  34 .Pp
  35 The network interfaces are named
  36 .Sy tun Ns Ar 0 ,
  37 .Sy tun Ns Ar 1 ,
  38 etc, as many in all as the
  39 .Ar count
  40 figure given on the
  41 .Sy pseudo-device
  42 line.  Each one supports the usual network-interface
  43 .Xr ioctl 2 Ns s ,
  44 such as
  45 .Dv SIOCSIFADDR
  46 and
  47 .Dv SIOCSIFNETMASK ,
  48 and thus can be used with
  49 .Xr ifconfig 8
  50 like any other interface.  At boot time, they are
  51 .Dv POINTOPOINT
  52 interfaces, but this can be changed; see the description of the control
  53 device, below.  When the system chooses to transmit a packet on the
  54 network interface, the packet can be read from the control device (it
  55 appears as
  56 .Dq input
  57 there); writing a packet to the control device generates an input
  58 packet on the network interface, as if the (nonexistent) hardware had
  59 just received it.
  60 .Pp
  61 There are two control interfaces.  The
  62 .Em data
  63 interface, normally
  64 .Pa /dev/tun Ns Sy N ,
  65 is exclusive-open (it cannot be opened if it is already open), is
  66 normally restricted to the super-user, and can
  67 .Dq transmit
  68 and
  69 .Dq receive
  70 packets.  The
  71 .Em control
  72 interface, normally
  73 .Pa /dev/tunc Ns Sy N ,
  74 cannot send and receive packets, but can be opened by many processes at
  75 once; it is intended for status queries and changes (many of which can
  76 also be implemented with
  77 .Fn ioctl
  78 calls on the data interface).  There are a number of status bits that
  79 can be set or cleared via the control interfaces; they are mentioned
  80 below where applicable, and they are all summarized in the discussions
  81 of the control interfaces.
  82 .\" Why isn't .Ss documented in mdoc(7) and mdoc.samples(7)?
  83 .Ss The data interface
  84 The data interface supports
  85 .Xr read 2 ,
  86 .Xr write 2 ,
  87 and
  88 .Xr ioctl 2
  89 calls to, respectively, collect
  90 .Dq output
  91 packets, generate
  92 .Dq input
  93 packets, and perform control functions.  As mentioned above, this
  94 interface is exclusive-open; if the
  95 .Dv SUONLY
  96 bit is set (which it is by default), it cannot be opened at all except
  97 by the super-user.  By default, a
  98 .Fn read
  99 call will return an error
 100 .Pf ( Er EHOSTDOWN )
 101 if the interface is not
 102 .Dq ready
 103 (which means that the control device is open and the interface's
 104 address has been set); if preferred, the
 105 .Dv RRWAIT
 106 bit can be set, in which case a
 107 .Fn read
 108 call will block (even if non-blocking I/O has been enabled) until the
 109 interface is ready.  Once the interface is ready,
 110 .Fn read
 111 will return a packet if one is available; if not, it will either block
 112 until one is or return
 113 .Er EWOULDBLOCK ,
 114 depending on whether non-blocking I/O has been enabled.  If the packet
 115 is longer than is allowed for in the buffer passed to
 116 .Fn read ,
 117 the extra data will be silently dropped.
 118 .Pp
 119 The first byte of data will always be the address family (eg,
 120 .Dv AF_INET )
 121 of the packet.  By default, the packet data follows immediately, but if
 122 the
 123 .Dv PREPADDR
 124 bit is set, the address to which the packet is to be sent is placed
 125 after the address family byte and before the packet data.  The size and
 126 layout of the address depends on the address family; for
 127 .Dv AF_INET ,
 128 for example, it is a
 129 .Va struct in_addr .
 130 A
 131 .Xr write 2
 132 call passes a packet in to be
 133 .Dq received
 134 on the pseudo-interface.  Each
 135 .Fn write
 136 call supplies exactly one packet; the packet length is taken from the
 137 amount of data provided to
 138 .Fn write .
 139 The first byte must be the address family of the packet, much as in
 140 packets returned by
 141 .Fn read ;
 142 the packet data always follows immediately.
 143 A large number of
 144 .Xr ioctl 2
 145 calls are also supported.  They are defined in
 146 .Aq Pa net/if_tun.h Ns .
 147 .Bl -tag -width TUN_PREPADDR
 148 .It Dv TUNSDEBUG
 149 The argument should be a pointer to an
 150 .Va int ;
 151 this sets the internal debugging variable to that value.  What, if
 152 anything, this variable controls is not documented here; see the source
 153 code.
 154 .It Dv TUNGDEBUG
 155 The argument should be a pointer to an
 156 .Va int ;
 157 this stores the internal debugging variable's value into it.
 158 .It Dv TUNSMODE
 159 The argument should be a pointer to an
 160 .Va int ;
 161 its value must be
 162 .Dv IFF_POINTOPOINT
 163 or
 164 .Dv IFF_BROADCAST .
 165 The type of the corresponding
 166 .Em tun Ns Sy n
 167 interface is set to the supplied type.  If the value is anything else,
 168 an
 169 .Er EINVAL
 170 error occurs.  The interface must be down at the time; if it is up, an
 171 .Er EBUSY
 172 error occurs.
 173 .\" X .It Dv TUNSFLAG
 174 .\" X The interface's flag bits are set as specified in the
 175 .\" X .Va int
 176 .\" X argument.  Only some of the bits can be modified; the rest are
 177 .\" X read-only.  The bits are defined in
 178 .\" X .Aq Pa net/if_tun.h
 179 .\" X with a
 180 .\" X .Dv TUN_
 181 .\" X prefix; for example, the bit called
 182 .\" X .Dv RRWAIT
 183 .\" X in this document would be referred to in source code as
 184 .\" X .Dv TUN_RRWAIT .
 185 .\" X The bits are:
 186 .\" X .\" Why isn't the way to create a table like this documented in mdoc(7)
 187 .\" X .\" or mdoc.samples(7)?!
 188 .\" X .Bl -column "TUN_PREPADDR" "RO/RW" -compact -indent-two
 189 .\" X .It Name Ta RO/RW Ta Meaning
 190 .\" X .It Dv TUN_OPEN Ta RO Ta "Data control device is open."
 191 .\" X .It Dv TUN_INITED Ta RO Ta "Initialized."
 192 .\" X .It Dv TUN_RCOLL Ta RO Ta "Select-for-read collision."
 193 .\" X .It Dv TUN_IASET Ta RO Ta "Address has been set."
 194 .\" X .It Dv TUN_DSTADDR Ta RO Ta "Destination address has been set."
 195 .\" X .It Dv TUN_RWAIT Ta RO Ta "A process is blocked in Fn read Ns ."
 196 .\" X .It Dv TUN_ASYNC Ta RO Ta "Generate Dv SIGIO No for readers."
 197 .\" X .It Dv TUN_NBIO Ta RO Ta "Non-blocking I/O for reads."
 198 .\" X .It Dv TUN_BRDADDR Ta RO Ta "Broadcast address has been set."
 199 .\" X .It Dv TUN_PREPADDR Ta RW Ta "Prepend sent-to address for reads."
 200 .\" X .It Dv TUN_STAYUP Ta RW Ta "Don't take interface down on close."
 201 .\" X .It Dv TUN_SUONLY Ta RW Ta "Data control device is super-user only."
 202 .\" X .It Dv TUN_RRWAIT Ta RW Ta "Wait for ready when reading."
 203 .\" X .El
 204 .\" X .It Dv TUNGFLAG
 205 .\" X The interface's flag bits are fetched into the argument
 206 .\" X .Va int .
 207 .\" X The flags and their meanings are as for
 208 .\" X .Dv TUNSFLAG .
 209 .\" X .It Dv FIONBIO
 210 .\" X Turn non-blocking I/O for reads off or on, according as the argument
 211 .\" X .Va int Ns 's
 212 .\" X value is or isn't zero.  (Writes are always nonblocking.)
 213 .\" X .It Dv FIOASYNC
 214 .\" X Turn asynchronous I/O for reads (ie, generation of
 215 .\" X .Dv SIGIO
 216 .\" X when data is available to be read) off or on, according as the argument
 217 .\" X .Va int Ns 's
 218 .\" X value is or isn't zero.
 219 .\" X .It Dv FIONREAD
 220 .\" X If any packets are queued to be read, store the size of the first one
 221 .\" X into the argument
 222 .\" X .Va int ;
 223 .\" X otherwise, store zero.
 224 .\" X .It Dv TIOCSPGRP
 225 .\" X Set the process group to receive
 226 .\" X .Dv SIGIO
 227 .\" X signals, when asynchronous I/O is enabled, to the argument
 228 .\" X .Va int
 229 .\" X value.
 230 .\" X .It Dv TIOCGPGRP
 231 .\" X Retrieve the process group value for
 232 .\" X .Dv SIGIO
 233 .\" X signals into the argument
 234 .\" X .Va int
 235 .\" X value.
 236 .El
 237 The data control device also supports
 238 .Xr select 2
 239 for read; selecting for write is pointless, and always succeeds, since
 240 writes are always nonblocking (if the packet cannot be accepted for a
 241 transient reason (eg, no buffer space available), it is silently
 242 dropped; if the reason is not transient (eg, packet too large), an
 243 error is returned).
 244 .Pp
 245 On the last close of the data device, by default, the interface is
 246 brought down (as if with
 247 .Dq ifconfig tun Ns Sy n down ) ;
 248 if the
 249 .Dv STAYUP
 250 bit is set, this is not done.  In either case, all queued packets are
 251 thrown away.  (If the interface is up when the data device is not open,
 252 either because of
 253 .Dv STAYUP
 254 or because it was explicitly brought up, output packets are always
 255 thrown away rather than letting them pile up.)
 256 .Ss The control interface
 257 The alternative control interface is a text-based interface designed
 258 for shell-script or human use; it allows control of many of the things
 259 that can be done with
 260 .Fn ioctl
 261 calls on the data interface, and a few more as well.
 262 .Pp
 263 .Fn read Ns s
 264 on the control interface always return a single line of text (or just
 265 the beginning of the line, if the buffer passed to
 266 .Xr read 2
 267 was too small to take the whole line).  The line contains items in the
 268 general format
 269 .Do
 270 .Li item=value
 271 .Dc ,
 272 where
 273 .Li item
 274 is a keyword and
 275 .Li value
 276 is a value appropriate to the keyword.  This line is intended for human
 277 use; programs should use the
 278 .Fn ioctl
 279 interface.  Here is an actual example (broken because of width
 280 restrictions):
 281 .Bd -literal
 282 unit=0 flags=(open,inited,!rcoll,iaset,!dstaddr,!rwait,!async,
 283 !nbio,!brdaddr,prepaddr,stayup,suonly,rrwait) type=broadcast
 284 mtu=1500 coll=0 ipkts=0/0 opkts=0/0 pgrp=0
 285 .Ed
 286 .Pp
 287 Note that the current file offset is ignored for reads, so using a tool like
 288 .Xr cat 1
 289 will result in infinite output.  Use something more like
 290 .Dq head\ \&-1
 291 for command-line use.  It is possible to
 292 .Xr select 2
 293 for reading on this device, which will indicate that the device is
 294 readable whenever the state is changed.
 295 .Pp
 296 Writes to the control interface are interpreted as modifications to the
 297 state.  Each
 298 .Fn write
 299 call is treated separately.  The data written is broken at whitespace
 300 (blanks, tabs, newlines); each resulting fragment has its first
 301 character examined.  If this character is a
 302 .Ql \&+
 303 or
 304 .Ql \&\- ,
 305 the rest of the fragment is taken as a flag name, and the flag is
 306 turned on (for
 307 .Ql \&+ )
 308 or off (for
 309 .Ql \&\- ) .
 310 (Flag names are as generated on reads; they are the same as the
 311 .Dv TUN_ Ns Em xxx
 312 constants, with the leading
 313 .Dv TUN_
 314 removed and the rest lowercased.)  If the first character is
 315 .Ql t ,
 316 the second character must be
 317 .Ql b
 318 or
 319 .Ql p ,
 320 and the interface type is set to
 321 .Dv IFF_BROADCAST
 322 or
 323 .Dv IFF_POINTOPOINT ,
 324 respectively.  If the first character is
 325 .Ql g
 326 or
 327 .Ql m ,
 328 the rest of the fragment is taken as a number in decimal (possibly with
 329 a leading \&\- sign) and the result is taken as a new process group,
 330 for
 331 .Ql g
 332 or MTU, for
 333 .Ql m .
 334 (The MTU must not be less than 1; attempts to set it so return
 335 .Er EIO . )
 336 .Pp
 337 This interface is useful for command-line reconfiguration, such as
 338 setting the interface type at boot time, with
 339 .Sh SEE ALSO
 340 .Xr inet 4 ,
 341 .Xr intro 4
 342 .Sh BUGS
 343 The
 344 .Dv SUONLY
 345 bit is a botch, especially since the control interface, which is never
 346 restricted by the kernel, can change it.  Access control really should
 347 be handled by the permission bits on the
 348 .Pa /dev
 349 entries for the data and control devices; this bit is a historical
 350 artifact.
 351 .Pp
 352 The process-group values for
 353 .Dv SIGIO
 354 signals should be checked; as it stands, the driver can be used (by
 355 anyone who can open the control or data device) to send any desired
 356 signal to an arbitrary process or process group.  (Until this is fixed,
 357 you should be careful to set the permisison bits to allow only root to
 358 open the control device, and either do the same for the data device or
 359 leave the
 360 .Dv SUONLY
 361 bit set.)