9 .Nd Ethernet tunnel software network interface
15 interface is a software loopback mechanism that can be loosely
16 described as the network interface analog of the
20 does for network interfaces what the
22 driver does for terminals.
28 driver, provides two interfaces: an interface like the usual facility
30 (an Ethernet network interface in the case of
34 and a character-special device
37 A client program transfers Ethernet frames to or from the
43 interface provides similar functionality at the network layer:
44 a client will transfer IP (by default) packets to or from a
49 The network interfaces are named
52 etc., one for each control device that has been opened.
53 These Ethernet network interfaces persist until
55 module is unloaded, or until removed with "ifconfig destroy" (see below).
58 devices are created using interface cloning.
59 This is done using the
60 .Dq ifconfig tap Ns Sy N No create
62 This is the preferred method of creating
65 The same method allows removal of interfaces.
67 .Dq ifconfig tap Ns Sy N No destroy
73 .Va net.link.tap.devfs_cloning
77 permits opens on the special control device
79 When this device is opened,
81 will return a handle for the lowest unused
88 Disabling the legacy devfs cloning functionality may break existing
89 applications which use
95 It therefore defaults to being enabled until further notice.
98 Control devices (once successfully opened) persist until
100 is unloaded or the interface is destroyed.
102 Each interface supports the usual Ethernet network interface
104 and thus can be used with
106 like any other Ethernet interface.
107 When the system chooses to transmit
108 an Ethernet frame on the network interface, the frame can be read from
113 writing an Ethernet frame to the control device generates an input frame on
114 the network interface, as if the
116 hardware had just received it.
118 The Ethernet tunnel device, normally
119 .Pa /dev/tap Ns Sy N ,
121 (it cannot be opened if it is already open)
122 and is restricted to the super-user, unless the
125 .Va net.link.tap.user_open
130 .Va net.link.tap.up_on_open
131 is non-zero, the tunnel device will be marked
133 when the control device is opened.
136 call will return an error
138 if the interface is not
140 Once the interface is ready,
142 will return an Ethernet frame if one is available; if not, it will
143 either block until one is or return
145 depending on whether non-blocking I/O has been enabled.
147 is longer than is allowed for in the buffer passed to
149 the extra data will be silently dropped.
153 call passes an Ethernet frame in to be
155 on the pseudo-interface.
158 call supplies exactly one frame; the frame length is taken from the
159 amount of data provided to
161 Writes will not block; if the frame cannot be accepted
162 for a transient reason
163 (e.g., no buffer space available),
164 it is silently dropped; if the reason is not transient
165 (e.g., frame too large),
166 an error is returned.
172 .Bl -tag -width VMIO_SIOCSETMACADDR
174 Set network interface information (line speed and MTU).
175 The type must be the same as returned by
182 The argument should be a pointer to a
185 Retrieve network interface information (line speed, MTU and type).
186 The argument should be a pointer to a
189 The argument should be a pointer to an
191 this sets the internal debugging variable to that value.
193 anything, this variable controls is not documented here; see the source
196 The argument should be a pointer to an
198 this stores the internal debugging variable's value into it.
200 Retrieve network interface name.
201 The argument should be a pointer to a
203 The interface name will be returned in the
207 Turn non-blocking I/O for reads off or on, according as the argument
209 value is or is not zero
210 (Writes are always nonblocking).
212 Turn asynchronous I/O for reads
215 when data is available to be read)
216 off or on, according as the argument
218 value is or is not zero.
220 If any frames are queued to be read, store the size of the first one into the argument
222 otherwise, store zero.
224 Set the process group to receive
226 signals, when asynchronous I/O is enabled, to the argument
230 Retrieve the process group value for
232 signals into the argument
236 Retrieve the Media Access Control
241 This command is used by the VMware port and expected to be executed on
242 descriptor, associated with control device
244 .Pa /dev/vmnet Ns Sy N
246 .Pa /dev/tap Ns Sy N ) .
249 which is passed as the argument, is expected to have enough space to store
253 At the open time both
258 addresses are the same, so this command could be used to retrieve the
263 Set the Media Access Control
268 This command is used by VMware port and expected to be executed on
269 a descriptor, associated with control device
271 .Pa /dev/vmnet Ns Sy N ) .
274 The control device also supports
276 for read; selecting for write is pointless, and always succeeds, since
277 writes are always non-blocking.
279 On the last close of the data device, the interface is
282 .Dq ifconfig tap Ns Sy N No down )
283 unless the device is a
288 All queued frames are thrown away.
289 If the interface is up when the data
290 device is not open, output frames are thrown away rather than
291 letting them pile up.
295 device can also be used with the VMware port as a replacement
302 themselves down when the
303 control device is closed.
304 Everything else is the same.
306 In addition to the above mentioned
308 calls, there is an additional one for the VMware port.
309 .Bl -tag -width VMIO_SIOCSETMACADDR
310 .It Dv VMIO_SIOCSIFFLAGS