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 .\" $DragonFly: src/share/man/man4/tun.4,v 1.3 2006/05/26 19:39:39 swildner Exp $
11 .Nd tunnel software network interface
17 interface is a software loopback mechanism that can be loosely
18 described as the network interface analog of the
22 does for network interfaces what the
24 driver does for terminals.
30 driver, provides two interfaces: an interface like the usual facility
32 (a network interface in the case of
36 and a character-special device
40 The network interfaces are named
43 etc, and each one supports the usual network-interface
49 and thus can be used with
51 like any other interface.
52 At boot time, they are
54 interfaces, but this can be changed; see the description of the control
56 When the system chooses to transmit a packet on the
57 network interface, the packet can be read from the control device
61 writing a packet to the control device generates an input
62 packet on the network interface, as if the (non\-existent)
63 hardware had just received it.
65 The tunnel device, normally
66 .Pa /dev/tun Ns Ar N ,
68 (it cannot be opened if it is already open)
69 and is restricted to the super-user.
72 call will return an error
74 if the interface is not
76 (which means that the control device is open and the interface's
77 address has been set).
79 Once the interface is ready,
81 will return a packet if one is available; if not, it will either block
82 until one is or return
84 depending on whether non-blocking I/O has been enabled.
85 If the packet is longer than is allowed for in the buffer passed to
87 the extra data will be silently dropped.
89 Packets can be optionally prepended with the destination address as presented
90 to the network interface output routine,
92 The destination address is in
95 The actual length of the prepended address is in the member
97 The packet data follows immediately.
101 call passes a packet in to be
103 on the pseudo-interface.
106 call supplies exactly one packet; the packet length is taken from the
107 amount of data provided to
109 Writes will not block; if the packet cannot be accepted for a
111 (e.g., no buffer space available),
112 it is silently dropped; if the reason is not transient
113 (e.g., packet too large),
114 an error is returned.
121 the actual packet data must be preceded by a
122 .Vt struct sockaddr .
123 The driver currently only inspects the
131 .In net/tun/if_tun.h ) :
132 .Bl -tag -width ".Dv TUNSIFMODE"
134 The argument should be a pointer to an
136 this sets the internal debugging variable to that value.
137 What, if anything, this variable controls is not documented here; see
140 The argument should be a pointer to an
142 this stores the internal debugging variable's value into it.
144 The argument should be a pointer to an
146 and allows setting the MTU, the type, and the baudrate of the tunnel
151 .In net/tun/if_tun.h .
153 The argument should be a pointer to an
155 where the current MTU, type, and baudrate will be stored.
157 The argument should be a pointer to an
159 its value must be either
163 The type of the corresponding
165 interface is set to the supplied type.
166 If the value is anything else, an
169 The interface must be down at the time; if it is up, an
173 The argument should be a pointer to an
175 a non-zero value turns on
177 mode, causing packets read from the tunnel device to be prepended with
178 network destination address.
180 Will set the pid owning the tunnel device to the current process's pid.
182 The argument should be a pointer to an
184 a non-zero value turns off
188 mode, where every packet is preceded with a four byte address family.
190 The argument should be a pointer to an
192 this stores one if the device is in
194 mode, and zero otherwise in it.
196 Turn non-blocking I/O for reads off or on, according as the argument
198 value is or isn't zero.
199 (Writes are always non-blocking.)
201 Turn asynchronous I/O for reads
204 when data is available to be read)
205 off or on, according as the argument
207 value is or isn't zero.
209 If any packets are queued to be read, store the size of the first one
212 otherwise, store zero.
214 Set the process group to receive
216 signals, when asynchronous I/O is enabled, to the argument
220 Retrieve the process group value for
222 signals into the argument
227 The control device also supports
229 for read; selecting for write is pointless, and always succeeds, since
230 writes are always non-blocking.
232 On the last close of the data device, by default, the interface is
235 .Nm ifconfig Ar tunN Cm down ) .
236 All queued packets are thrown away.
237 If the interface is up when the data device is not open
238 output packets are always thrown away rather than letting
244 This manual page was originally obtained from