]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man4/tun.4
xnu-1228.7.58.tar.gz
[apple/xnu.git] / bsd / man / man4 / tun.4
... / ...
CommitLineData
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
11The
12.Nm tun
13interface is a software loopback mechanism that can be loosely
14described as the network interface analog of the
15.Xr pty 4 ,
16that is,
17.Nm tun
18does for network interfaces what the
19.Nm pty
20driver does for terminals.
21.Pp
22The
23.Nm tun
24driver, like the
25.Nm pty
26driver, provides two interfaces: an interface like the usual facility
27it is simulating (a network interface in the case of
28.Nm tun ,
29or a terinal for
30.Nm pty ) ,
31and a character-special device
32.Dq control
33interface.
34.Pp
35The network interfaces are named
36.Sy tun Ns Ar 0 ,
37.Sy tun Ns Ar 1 ,
38etc, as many in all as the
39.Ar count
40figure given on the
41.Sy pseudo-device
42line. Each one supports the usual network-interface
43.Xr ioctl 2 Ns s ,
44such as
45.Dv SIOCSIFADDR
46and
47.Dv SIOCSIFNETMASK ,
48and thus can be used with
49.Xr ifconfig 8
50like any other interface. At boot time, they are
51.Dv POINTOPOINT
52interfaces, but this can be changed; see the description of the control
53device, below. When the system chooses to transmit a packet on the
54network interface, the packet can be read from the control device (it
55appears as
56.Dq input
57there); writing a packet to the control device generates an input
58packet on the network interface, as if the (nonexistent) hardware had
59just received it.
60.Pp
61There are two control interfaces. The
62.Em data
63interface, normally
64.Pa /dev/tun Ns Sy N ,
65is exclusive-open (it cannot be opened if it is already open), is
66normally restricted to the super-user, and can
67.Dq transmit
68and
69.Dq receive
70packets. The
71.Em control
72interface, normally
73.Pa /dev/tunc Ns Sy N ,
74cannot send and receive packets, but can be opened by many processes at
75once; it is intended for status queries and changes (many of which can
76also be implemented with
77.Fn ioctl
78calls on the data interface). There are a number of status bits that
79can be set or cleared via the control interfaces; they are mentioned
80below where applicable, and they are all summarized in the discussions
81of the control interfaces.
82.\" Why isn't .Ss documented in mdoc(7) and mdoc.samples(7)?
83.Ss The data interface
84The data interface supports
85.Xr read 2 ,
86.Xr write 2 ,
87and
88.Xr ioctl 2
89calls to, respectively, collect
90.Dq output
91packets, generate
92.Dq input
93packets, and perform control functions. As mentioned above, this
94interface is exclusive-open; if the
95.Dv SUONLY
96bit is set (which it is by default), it cannot be opened at all except
97by the super-user. By default, a
98.Fn read
99call will return an error
100.Pf ( Er EHOSTDOWN )
101if the interface is not
102.Dq ready
103(which means that the control device is open and the interface's
104address has been set); if preferred, the
105.Dv RRWAIT
106bit can be set, in which case a
107.Fn read
108call will block (even if non-blocking I/O has been enabled) until the
109interface is ready. Once the interface is ready,
110.Fn read
111will return a packet if one is available; if not, it will either block
112until one is or return
113.Er EWOULDBLOCK ,
114depending on whether non-blocking I/O has been enabled. If the packet
115is longer than is allowed for in the buffer passed to
116.Fn read ,
117the extra data will be silently dropped.
118.Pp
119The first byte of data will always be the address family (eg,
120.Dv AF_INET )
121of the packet. By default, the packet data follows immediately, but if
122the
123.Dv PREPADDR
124bit is set, the address to which the packet is to be sent is placed
125after the address family byte and before the packet data. The size and
126layout of the address depends on the address family; for
127.Dv AF_INET ,
128for example, it is a
129.Va struct in_addr .
130A
131.Xr write 2
132call passes a packet in to be
133.Dq received
134on the pseudo-interface. Each
135.Fn write
136call supplies exactly one packet; the packet length is taken from the
137amount of data provided to
138.Fn write .
139The first byte must be the address family of the packet, much as in
140packets returned by
141.Fn read ;
142the packet data always follows immediately.
143A large number of
144.Xr ioctl 2
145calls 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
149The argument should be a pointer to an
150.Va int ;
151this sets the internal debugging variable to that value. What, if
152anything, this variable controls is not documented here; see the source
153code.
154.It Dv TUNGDEBUG
155The argument should be a pointer to an
156.Va int ;
157this stores the internal debugging variable's value into it.
158.It Dv TUNSMODE
159The argument should be a pointer to an
160.Va int ;
161its value must be
162.Dv IFF_POINTOPOINT
163or
164.Dv IFF_BROADCAST .
165The type of the corresponding
166.Em tun Ns Sy n
167interface is set to the supplied type. If the value is anything else,
168an
169.Er EINVAL
170error occurs. The interface must be down at the time; if it is up, an
171.Er EBUSY
172error 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
237The data control device also supports
238.Xr select 2
239for read; selecting for write is pointless, and always succeeds, since
240writes are always nonblocking (if the packet cannot be accepted for a
241transient reason (eg, no buffer space available), it is silently
242dropped; if the reason is not transient (eg, packet too large), an
243error is returned).
244.Pp
245On the last close of the data device, by default, the interface is
246brought down (as if with
247.Dq ifconfig tun Ns Sy n down ) ;
248if the
249.Dv STAYUP
250bit is set, this is not done. In either case, all queued packets are
251thrown away. (If the interface is up when the data device is not open,
252either because of
253.Dv STAYUP
254or because it was explicitly brought up, output packets are always
255thrown away rather than letting them pile up.)
256.Ss The control interface
257The alternative control interface is a text-based interface designed
258for shell-script or human use; it allows control of many of the things
259that can be done with
260.Fn ioctl
261calls on the data interface, and a few more as well.
262.Pp
263.Fn read Ns s
264on the control interface always return a single line of text (or just
265the beginning of the line, if the buffer passed to
266.Xr read 2
267was too small to take the whole line). The line contains items in the
268general format
269.Do
270.Li item=value
271.Dc ,
272where
273.Li item
274is a keyword and
275.Li value
276is a value appropriate to the keyword. This line is intended for human
277use; programs should use the
278.Fn ioctl
279interface. Here is an actual example (broken because of width
280restrictions):
281.Bd -literal
282unit=0 flags=(open,inited,!rcoll,iaset,!dstaddr,!rwait,!async,
283!nbio,!brdaddr,prepaddr,stayup,suonly,rrwait) type=broadcast
284mtu=1500 coll=0 ipkts=0/0 opkts=0/0 pgrp=0
285.Ed
286.Pp
287Note that the current file offset is ignored for reads, so using a tool like
288.Xr cat 1
289will result in infinite output. Use something more like
290.Dq head\ \&-1
291for command-line use. It is possible to
292.Xr select 2
293for reading on this device, which will indicate that the device is
294readable whenever the state is changed.
295.Pp
296Writes to the control interface are interpreted as modifications to the
297state. Each
298.Fn write
299call is treated separately. The data written is broken at whitespace
300(blanks, tabs, newlines); each resulting fragment has its first
301character examined. If this character is a
302.Ql \&+
303or
304.Ql \&\- ,
305the rest of the fragment is taken as a flag name, and the flag is
306turned on (for
307.Ql \&+ )
308or off (for
309.Ql \&\- ) .
310(Flag names are as generated on reads; they are the same as the
311.Dv TUN_ Ns Em xxx
312constants, with the leading
313.Dv TUN_
314removed and the rest lowercased.) If the first character is
315.Ql t ,
316the second character must be
317.Ql b
318or
319.Ql p ,
320and the interface type is set to
321.Dv IFF_BROADCAST
322or
323.Dv IFF_POINTOPOINT ,
324respectively. If the first character is
325.Ql g
326or
327.Ql m ,
328the rest of the fragment is taken as a number in decimal (possibly with
329a leading \&\- sign) and the result is taken as a new process group,
330for
331.Ql g
332or 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
337This interface is useful for command-line reconfiguration, such as
338setting the interface type at boot time, with
339.Sh SEE ALSO
340.Xr inet 4 ,
341.Xr intro 4
342.Sh BUGS
343The
344.Dv SUONLY
345bit is a botch, especially since the control interface, which is never
346restricted by the kernel, can change it. Access control really should
347be handled by the permission bits on the
348.Pa /dev
349entries for the data and control devices; this bit is a historical
350artifact.
351.Pp
352The process-group values for
353.Dv SIGIO
354signals should be checked; as it stands, the driver can be used (by
355anyone who can open the control or data device) to send any desired
356signal to an arbitrary process or process group. (Until this is fixed,
357you should be careful to set the permisison bits to allow only root to
358open the control device, and either do the same for the data device or
359leave the
360.Dv SUONLY
361bit set.)