1 .\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
10 .Nd tunnel software network interface
12 To compile this driver into the kernel,
13 place the following line in your
14 kernel configuration file:
15 .Bd -ragged -offset indent
19 Alternatively, to load the driver as a
20 module at boot time, place the following lines in
22 .Bd -literal -offset indent
28 interface is a software loopback mechanism that can be loosely
29 described as the network interface analog of the
33 does for network interfaces what the
35 driver does for terminals.
41 driver, provides two interfaces: an interface like the usual facility
43 (a network interface in the case of
47 and a character-special device
50 A client program transfers IP (by default) packets to or from the
56 interface provides similar functionality at the Ethernet layer:
57 a client will transfer Ethernet frames to or from a
62 The network interfaces are named
65 etc., one for each control device that has been opened.
66 These network interfaces persist until the
68 module is unloaded, or until removed with the
73 devices are created using interface cloning.
74 This is done using the
75 .Dq ifconfig tun Ns Sy N No create
77 This is the preferred method of creating
80 The same method allows removal of interfaces.
82 .Dq ifconfig tun Ns Sy N No destroy
88 .Va net.link.tun.devfs_cloning
92 permits opens on the special control device
94 When this device is opened,
96 will return a handle for the lowest unused
103 Disabling the legacy devfs cloning functionality may break existing
104 applications which use
110 It therefore defaults to being enabled until further notice.
113 Control devices (once successfully opened) persist until
115 is unloaded in the same way that network interfaces persist (see above).
117 Each interface supports the usual network-interface
121 and thus can be used with
123 like any other interface.
124 At boot time, they are
126 interfaces, but this can be changed; see the description of the control
128 When the system chooses to transmit a packet on the
129 network interface, the packet can be read from the control device
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.
138 .Pq Pa /dev/tun Ns Ar N
140 (it cannot be opened if it is already open).
143 call will return an error
145 if the interface is not
147 (which means that the control device is open and the interface's
148 address has been set).
150 Once the interface is ready,
152 will return a packet if one is available; if not, it will either block
153 until one is or return
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
158 the extra data will be silently dropped.
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
166 The destination address is in
169 The actual length of the prepended address is in the member
173 ioctl has been set, packets will be prepended with a four byte address
174 family in network byte order.
178 are mutually exclusive.
179 In any case, the packet data follows immediately.
183 call passes a packet in to be
185 on the pseudo-interface.
188 ioctl has been set, the address family must be prepended, otherwise the
189 packet is assumed to be of type
193 call supplies exactly one packet; the packet length is taken from the
194 amount of data provided to
196 (minus any supplied address family).
197 Writes will not block; if the packet cannot be accepted for a
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.
209 .Bl -tag -width ".Dv TUNSIFMODE"
211 The argument should be a pointer to an
213 this sets the internal debugging variable to that value.
214 What, if anything, this variable controls is not documented here; see
217 The argument should be a pointer to an
219 this stores the internal debugging variable's value into it.
221 The argument should be a pointer to an
223 and allows setting the MTU and the baudrate of the tunnel
225 The type must be the same as returned by
237 The use of this ioctl is restricted to the super-user.
239 The argument should be a pointer to an
241 where the current MTU, type, and baudrate will be stored.
243 The argument should be a pointer to an
245 its value must be either
251 OR'd into the value if multicast support is required.
252 The type of the corresponding
254 interface is set to the supplied type.
255 If the value is outside the above range, an
258 The interface must be down at the time; if it is up, an
262 The argument should be a pointer to an
264 a non-zero value turns off
268 mode, causing packets read from the tunnel device to be prepended with
269 the network destination address (see above).
271 Will set the pid owning the tunnel device to the current process's pid.
273 The argument should be a pointer to an
275 a non-zero value turns off
279 mode, where every packet is preceded with a four byte address family.
281 The argument should be a pointer to an
283 the ioctl sets the value to one if the device is in
285 mode, and zero otherwise.
287 Turn non-blocking I/O for reads off or on, according as the argument
289 value is or is not zero.
290 (Writes are always non-blocking.)
292 Turn asynchronous I/O for reads
295 when data is available to be read)
296 off or on, according as the argument
298 value is or is not zero.
300 If any packets are queued to be read, store the size of the first one
303 otherwise, store zero.
305 Set the process group to receive
307 signals, when asynchronous I/O is enabled, to the argument
311 Retrieve the process group value for
313 signals into the argument
318 The control device also supports
320 for read; selecting for write is pointless, and always succeeds, since
321 writes are always non-blocking.
323 On the last close of the data device, by default, the interface is
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
343 This manual page was originally obtained from