5.Os
6.Dt TAP 4
7.Sh NAME
8.Nm tap
9.Nd Ethernet tunnel software network interface
10.Sh SYNOPSIS
11.Cd device tap
12.Sh DESCRIPTION
13The
14.Nm
15interface is a software loopback mechanism that can be loosely
16described as the network interface analog of the
17.Xr pty 4 ,
18that is,
19.Nm
20does for network interfaces what the
21.Nm pty
22driver does for terminals.
23.Pp
24The
25.Nm
26driver, like the
27.Nm pty
28driver, provides two interfaces: an interface like the usual facility
29it is simulating
30(an Ethernet network interface in the case of
31.Nm ,
32or a terminal for
33.Nm pty ) ,
34and a character-special device
35.Dq control
36interface.
37.Pp
38The network interfaces are named
39.Dq Li tap0 ,
40.Dq Li tap1 ,
41etc., one for each control device that has been opened.
42These Ethernet network interfaces persist until
43.Pa if_tap.ko
| 5.Os
6.Dt TAP 4
7.Sh NAME
8.Nm tap
9.Nd Ethernet tunnel software network interface
10.Sh SYNOPSIS
11.Cd device tap
12.Sh DESCRIPTION
13The
14.Nm
15interface is a software loopback mechanism that can be loosely
16described as the network interface analog of the
17.Xr pty 4 ,
18that is,
19.Nm
20does for network interfaces what the
21.Nm pty
22driver does for terminals.
23.Pp
24The
25.Nm
26driver, like the
27.Nm pty
28driver, provides two interfaces: an interface like the usual facility
29it is simulating
30(an Ethernet network interface in the case of
31.Nm ,
32or a terminal for
33.Nm pty ) ,
34and a character-special device
35.Dq control
36interface.
37.Pp
38The network interfaces are named
39.Dq Li tap0 ,
40.Dq Li tap1 ,
41etc., one for each control device that has been opened.
42These Ethernet network interfaces persist until
43.Pa if_tap.ko
|
63.Pp
64Each interface supports the usual Ethernet network interface
65.Xr ioctl 2 Ns s ,
66such as
67.Dv SIOCSIFADDR
68and
69.Dv SIOCSIFNETMASK ,
70and thus can be used with
71.Xr ifconfig 8
72like any other Ethernet interface.
73When the system chooses to transmit
74an Ethernet frame on the network interface, the frame can be read from
75the control device
76(it appears as
77.Dq input
78there);
79writing an Ethernet frame to the control device generates an input frame on
80the network interface, as if the
81(non-existent)
82hardware had just received it.
83.Pp
84The Ethernet tunnel device, normally
85.Pa /dev/tap Ns Sy N ,
86is exclusive-open
87(it cannot be opened if it is already open)
88and is restricted to the super-user, unless the
89.Xr sysctl 8
90variable
91.Va net.link.tap.user_open
92is non-zero.
93A
94.Fn read
95call will return an error
96.Pq Er EHOSTDOWN
97if the interface is not
98.Dq ready .
99Once the interface is ready,
100.Fn read
101will return an Ethernet frame if one is available; if not, it will
102either block until one is or return
103.Er EWOULDBLOCK ,
104depending on whether non-blocking I/O has been enabled.
105If the frame
106is longer than is allowed for in the buffer passed to
107.Fn read ,
108the extra data will be silently dropped.
109.Pp
110A
111.Xr write 2
112call passes an Ethernet frame in to be
113.Dq received
114on the pseudo-interface.
115Each
116.Fn write
117call supplies exactly one frame; the frame length is taken from the
118amount of data provided to
119.Fn write .
120Writes will not block; if the frame cannot be accepted
121for a transient reason
122(e.g., no buffer space available),
123it is silently dropped; if the reason is not transient
124(e.g., frame too large),
125an error is returned.
126The following
127.Xr ioctl 2
128calls are supported
129(defined in
130.In net/if_tap.h ) :
131.Bl -tag -width VMIO_SIOCSETMACADDR
132.It Dv TAPSDEBUG
133The argument should be a pointer to an
134.Va int ;
135this sets the internal debugging variable to that value.
136What, if
137anything, this variable controls is not documented here; see the source
138code.
139.It Dv TAPGDEBUG
140The argument should be a pointer to an
141.Va int ;
142this stores the internal debugging variable's value into it.
143.It Dv FIONBIO
144Turn non-blocking I/O for reads off or on, according as the argument
145.Va int Ns 's
146value is or is not zero
147(Writes are always nonblocking).
148.It Dv FIOASYNC
149Turn asynchronous I/O for reads
150(i.e., generation of
151.Dv SIGIO
152when data is available to be read)
153off or on, according as the argument
154.Va int Ns 's
155value is or is not zero.
156.It Dv FIONREAD
157If any frames are queued to be read, store the size of the first one into the argument
158.Va int ;
159otherwise, store zero.
160.It Dv TIOCSPGRP
161Set the process group to receive
162.Dv SIGIO
163signals, when asynchronous I/O is enabled, to the argument
164.Va int
165value.
166.It Dv TIOCGPGRP
167Retrieve the process group value for
168.Dv SIGIO
169signals into the argument
170.Va int
171value.
172.It Dv SIOCGIFADDR
173Retrieve the Media Access Control
174.Pq Dv MAC
175address of the
176.Dq remote
177side.
178This command is used by the VMware port and expected to be executed on
179descriptor, associated with control device
180(usually
181.Pa /dev/vmnet Ns Sy N
182or
183.Pa /dev/tap Ns Sy N ) .
184The
185.Va buffer ,
186which is passed as the argument, is expected to have enough space to store
187the
188.Dv MAC
189address.
190At the open time both
191.Dq local
192and
193.Dq remote
194.Dv MAC
195addresses are the same, so this command could be used to retrieve the
196.Dq local
197.Dv MAC
198address.
199.It Dv SIOCSIFADDR
200Set the Media Access Control
201.Pq Dv MAC
202address of the
203.Dq remote
204side.
205This command is used by VMware port and expected to be executed on
206a descriptor, associated with control device
207(usually
208.Pa /dev/vmnet Ns Sy N ) .
209.El
210.Pp
211The control device also supports
212.Xr select 2
213for read; selecting for write is pointless, and always succeeds, since
214writes are always non-blocking.
215.Pp
216On the last close of the data device, the interface is
217brought down
218(as if with
219.Dq ifconfig tap Ns Sy N No down )
220unless the device is a
221.Em VMnet
222device.
223All queued frames are thrown away.
224If the interface is up when the data
225device is not open, output frames are thrown away rather than
226letting them pile up.
227.Pp
228The
229.Nm
230device can also be used with the VMware port as a replacement
231for the old
232.Em VMnet
233device driver.
234The driver uses the minor number
235to select between
236.Nm
237and
238.Nm vmnet
239devices.
240.Em VMnet
241minor numbers begin at
242.Va 0x800000
243+
244.Va N ;
245where
246.Va N
247is a
248.Em VMnet
249unit number.
250In this case the control device is expected to be
251.Pa /dev/vmnet Ns Sy N ,
252and the network interface will be
253.Sy vmnet Ns Ar N .
254Additionally,
255.Em VMnet
256devices do not
257.Xr ifconfig 8
258themselves down when the
259control device is closed.
260Everything else is the same.
261.Pp
262In addition to the above mentioned
263.Xr ioctl 2
264calls, there is an additional one for the VMware port.
265.Bl -tag -width VMIO_SIOCSETMACADDR
266.It Dv VMIO_SIOCSIFFLAGS
267VMware
268.Dv SIOCSIFFLAGS .
269.El
270.Sh SEE ALSO
271.Xr inet 4 ,
272.Xr intro 4
| 90.Pp
91Each interface supports the usual Ethernet network interface
92.Xr ioctl 2 Ns s ,
93such as
94.Dv SIOCSIFADDR
95and
96.Dv SIOCSIFNETMASK ,
97and thus can be used with
98.Xr ifconfig 8
99like any other Ethernet interface.
100When the system chooses to transmit
101an Ethernet frame on the network interface, the frame can be read from
102the control device
103(it appears as
104.Dq input
105there);
106writing an Ethernet frame to the control device generates an input frame on
107the network interface, as if the
108(non-existent)
109hardware had just received it.
110.Pp
111The Ethernet tunnel device, normally
112.Pa /dev/tap Ns Sy N ,
113is exclusive-open
114(it cannot be opened if it is already open)
115and is restricted to the super-user, unless the
116.Xr sysctl 8
117variable
118.Va net.link.tap.user_open
119is non-zero.
120A
121.Fn read
122call will return an error
123.Pq Er EHOSTDOWN
124if the interface is not
125.Dq ready .
126Once the interface is ready,
127.Fn read
128will return an Ethernet frame if one is available; if not, it will
129either block until one is or return
130.Er EWOULDBLOCK ,
131depending on whether non-blocking I/O has been enabled.
132If the frame
133is longer than is allowed for in the buffer passed to
134.Fn read ,
135the extra data will be silently dropped.
136.Pp
137A
138.Xr write 2
139call passes an Ethernet frame in to be
140.Dq received
141on the pseudo-interface.
142Each
143.Fn write
144call supplies exactly one frame; the frame length is taken from the
145amount of data provided to
146.Fn write .
147Writes will not block; if the frame cannot be accepted
148for a transient reason
149(e.g., no buffer space available),
150it is silently dropped; if the reason is not transient
151(e.g., frame too large),
152an error is returned.
153The following
154.Xr ioctl 2
155calls are supported
156(defined in
157.In net/if_tap.h ) :
158.Bl -tag -width VMIO_SIOCSETMACADDR
159.It Dv TAPSDEBUG
160The argument should be a pointer to an
161.Va int ;
162this sets the internal debugging variable to that value.
163What, if
164anything, this variable controls is not documented here; see the source
165code.
166.It Dv TAPGDEBUG
167The argument should be a pointer to an
168.Va int ;
169this stores the internal debugging variable's value into it.
170.It Dv FIONBIO
171Turn non-blocking I/O for reads off or on, according as the argument
172.Va int Ns 's
173value is or is not zero
174(Writes are always nonblocking).
175.It Dv FIOASYNC
176Turn asynchronous I/O for reads
177(i.e., generation of
178.Dv SIGIO
179when data is available to be read)
180off or on, according as the argument
181.Va int Ns 's
182value is or is not zero.
183.It Dv FIONREAD
184If any frames are queued to be read, store the size of the first one into the argument
185.Va int ;
186otherwise, store zero.
187.It Dv TIOCSPGRP
188Set the process group to receive
189.Dv SIGIO
190signals, when asynchronous I/O is enabled, to the argument
191.Va int
192value.
193.It Dv TIOCGPGRP
194Retrieve the process group value for
195.Dv SIGIO
196signals into the argument
197.Va int
198value.
199.It Dv SIOCGIFADDR
200Retrieve the Media Access Control
201.Pq Dv MAC
202address of the
203.Dq remote
204side.
205This command is used by the VMware port and expected to be executed on
206descriptor, associated with control device
207(usually
208.Pa /dev/vmnet Ns Sy N
209or
210.Pa /dev/tap Ns Sy N ) .
211The
212.Va buffer ,
213which is passed as the argument, is expected to have enough space to store
214the
215.Dv MAC
216address.
217At the open time both
218.Dq local
219and
220.Dq remote
221.Dv MAC
222addresses are the same, so this command could be used to retrieve the
223.Dq local
224.Dv MAC
225address.
226.It Dv SIOCSIFADDR
227Set the Media Access Control
228.Pq Dv MAC
229address of the
230.Dq remote
231side.
232This command is used by VMware port and expected to be executed on
233a descriptor, associated with control device
234(usually
235.Pa /dev/vmnet Ns Sy N ) .
236.El
237.Pp
238The control device also supports
239.Xr select 2
240for read; selecting for write is pointless, and always succeeds, since
241writes are always non-blocking.
242.Pp
243On the last close of the data device, the interface is
244brought down
245(as if with
246.Dq ifconfig tap Ns Sy N No down )
247unless the device is a
248.Em VMnet
249device.
250All queued frames are thrown away.
251If the interface is up when the data
252device is not open, output frames are thrown away rather than
253letting them pile up.
254.Pp
255The
256.Nm
257device can also be used with the VMware port as a replacement
258for the old
259.Em VMnet
260device driver.
261The driver uses the minor number
262to select between
263.Nm
264and
265.Nm vmnet
266devices.
267.Em VMnet
268minor numbers begin at
269.Va 0x800000
270+
271.Va N ;
272where
273.Va N
274is a
275.Em VMnet
276unit number.
277In this case the control device is expected to be
278.Pa /dev/vmnet Ns Sy N ,
279and the network interface will be
280.Sy vmnet Ns Ar N .
281Additionally,
282.Em VMnet
283devices do not
284.Xr ifconfig 8
285themselves down when the
286control device is closed.
287Everything else is the same.
288.Pp
289In addition to the above mentioned
290.Xr ioctl 2
291calls, there is an additional one for the VMware port.
292.Bl -tag -width VMIO_SIOCSETMACADDR
293.It Dv VMIO_SIOCSIFFLAGS
294VMware
295.Dv SIOCSIFFLAGS .
296.El
297.Sh SEE ALSO
298.Xr inet 4 ,
299.Xr intro 4
|