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.2 2003/06/17 04:36:59 dillon 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, as many as were made by
45 Each one supports the usual network-interface
51 and thus can be used with
53 like any other interface.
54 At boot time, they are
56 interfaces, but this can be changed; see the description of the control
58 When the system chooses to transmit a packet on the
59 network interface, the packet can be read from the control device
63 writing a packet to the control device generates an input
64 packet on the network interface, as if the (non\-existent)
65 hardware had just received it.
67 The tunnel device, normally
68 .Pa /dev/tun Ns Ar N ,
70 (it cannot be opened if it is already open)
71 and is restricted to the super-user.
74 call will return an error
76 if the interface is not
78 (which means that the control device is open and the interface's
79 address has been set).
81 Once the interface is ready,
83 will return a packet if one is available; if not, it will either block
84 until one is or return
86 depending on whether non-blocking I/O has been enabled.
87 If the packet is longer than is allowed for in the buffer passed to
89 the extra data will be silently dropped.
91 Packets can be optionally prepended with the destination address as presented
92 to the network interface output routine,
94 The destination address is in
97 The actual length of the prepended address is in the member
99 The packet data follows immediately.
103 call passes a packet in to be
105 on the pseudo-interface.
108 call supplies exactly one packet; the packet length is taken from the
109 amount of data provided to
111 Writes will not block; if the packet cannot be accepted for a
113 (e.g., no buffer space available),
114 it is silently dropped; if the reason is not transient
115 (e.g., packet too large),
116 an error is returned.
123 the actual packet data must be preceded by a
124 .Vt struct sockaddr .
125 The driver currently only inspects the
133 .Aq Pa net/if_tun.h ) :
134 .Bl -tag -width ".Dv TUNSIFMODE"
136 The argument should be a pointer to an
138 this sets the internal debugging variable to that value.
139 What, if anything, this variable controls is not documented here; see
142 The argument should be a pointer to an
144 this stores the internal debugging variable's value into it.
146 The argument should be a pointer to an
148 and allows setting the MTU, the type, and the baudrate of the tunnel
153 .Aq Pa net/if_tun.h .
155 The argument should be a pointer to an
157 where the current MTU, type, and baudrate will be stored.
159 The argument should be a pointer to an
161 its value must be either
165 The type of the corresponding
167 interface is set to the supplied type.
168 If the value is anything else, an
171 The interface must be down at the time; if it is up, an
175 The argument should be a pointer to an
177 a non-zero value turns on
179 mode, causing packets read from the tunnel device to be prepended with
180 network destination address.
182 Will set the pid owning the tunnel device to the current process's pid.
184 The argument should be a pointer to an
186 a non-zero value turns off
190 mode, where every packet is preceded with a four byte address family.
192 The argument should be a pointer to an
194 this stores one if the device is in
196 mode, and zero otherwise in it.
198 Turn non-blocking I/O for reads off or on, according as the argument
200 value is or isn't zero.
201 (Writes are always non-blocking.)
203 Turn asynchronous I/O for reads
206 when data is available to be read)
207 off or on, according as the argument
209 value is or isn't zero.
211 If any packets are queued to be read, store the size of the first one
214 otherwise, store zero.
216 Set the process group to receive
218 signals, when asynchronous I/O is enabled, to the argument
222 Retrieve the process group value for
224 signals into the argument
229 The control device also supports
231 for read; selecting for write is pointless, and always succeeds, since
232 writes are always non-blocking.
234 On the last close of the data device, by default, the interface is
237 .Nm ifconfig Ar tunN Cm down ) .
238 All queued packets are thrown away.
239 If the interface is up when the data device is not open
240 output packets are always thrown away rather than letting
246 This manual page was originally obtained from