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
38 The network interfaces are named
41 etc., one for each control device that has been opened.
42 These Ethernet network interfaces persist until
44 module is unloaded, or until removed with "ifconfig destroy" (see below).
47 devices are created using interface cloning.
48 This is done using the
49 .Dq ifconfig tap Ns Sy N No create
51 This is the preferred method of creating
54 The same method allows removal of interfaces.
56 .Dq ifconfig tap Ns Sy N No destroy
62 .Va net.link.tap.devfs_cloning
66 permits opens on the special control device
68 When this device is opened,
70 will return a handle for the lowest unused
77 Disabling the legacy devfs cloning functionality may break existing
78 applications which use
84 It therefore defaults to being enabled until further notice.
87 Control devices (once successfully opened) persist until
89 is unloaded or the interface is destroyed.
91 Each interface supports the usual Ethernet network interface
97 and thus can be used with
99 like any other Ethernet interface.
100 When the system chooses to transmit
101 an Ethernet frame on the network interface, the frame can be read from
106 writing an Ethernet frame to the control device generates an input frame on
107 the network interface, as if the
109 hardware had just received it.
111 The Ethernet tunnel device, normally
112 .Pa /dev/tap Ns Sy N ,
114 (it cannot be opened if it is already open)
115 and is restricted to the super-user, unless the
118 .Va net.link.tap.user_open
123 .Va net.link.tap.up_on_open
124 is non-zero, the tunnel device will be marked
126 when the control device is opened.
129 call will return an error
131 if the interface is not
133 Once the interface is ready,
135 will return an Ethernet frame if one is available; if not, it will
136 either block until one is or return
138 depending on whether non-blocking I/O has been enabled.
140 is longer than is allowed for in the buffer passed to
142 the extra data will be silently dropped.
146 call passes an Ethernet frame in to be
148 on the pseudo-interface.
151 call supplies exactly one frame; the frame length is taken from the
152 amount of data provided to
154 Writes will not block; if the frame cannot be accepted
155 for a transient reason
156 (e.g., no buffer space available),
157 it is silently dropped; if the reason is not transient
158 (e.g., frame too large),
159 an error is returned.
165 .Bl -tag -width VMIO_SIOCSETMACADDR
167 Set network interface information (line speed, MTU and type).
168 The argument should be a pointer to a
171 Retrieve network interface information (line speed, MTU and type).
172 The argument should be a pointer to a
175 The argument should be a pointer to an
177 this sets the internal debugging variable to that value.
179 anything, this variable controls is not documented here; see the source
182 The argument should be a pointer to an
184 this stores the internal debugging variable's value into it.
186 Retrieve network interface name.
187 The argument should be a pointer to a
189 The interface name will be returned in the
193 Turn non-blocking I/O for reads off or on, according as the argument
195 value is or is not zero
196 (Writes are always nonblocking).
198 Turn asynchronous I/O for reads
201 when data is available to be read)
202 off or on, according as the argument
204 value is or is not zero.
206 If any frames are queued to be read, store the size of the first one into the argument
208 otherwise, store zero.
210 Set the process group to receive
212 signals, when asynchronous I/O is enabled, to the argument
216 Retrieve the process group value for
218 signals into the argument
222 Retrieve the Media Access Control
227 This command is used by the VMware port and expected to be executed on
228 descriptor, associated with control device
230 .Pa /dev/vmnet Ns Sy N
232 .Pa /dev/tap Ns Sy N ) .
235 which is passed as the argument, is expected to have enough space to store
239 At the open time both
244 addresses are the same, so this command could be used to retrieve the
249 Set the Media Access Control
254 This command is used by VMware port and expected to be executed on
255 a descriptor, associated with control device
257 .Pa /dev/vmnet Ns Sy N ) .
260 The control device also supports
262 for read; selecting for write is pointless, and always succeeds, since
263 writes are always non-blocking.
265 On the last close of the data device, the interface is
268 .Dq ifconfig tap Ns Sy N No down )
269 unless the device is a
272 All queued frames are thrown away.
273 If the interface is up when the data
274 device is not open, output frames are thrown away rather than
275 letting them pile up.
279 device can also be used with the VMware port as a replacement
283 The driver uses the minor number
290 minor numbers begin at
299 In this case the control device is expected to be
300 .Pa /dev/vmnet Ns Sy N ,
301 and the network interface will be
307 themselves down when the
308 control device is closed.
309 Everything else is the same.
311 In addition to the above mentioned
313 calls, there is an additional one for the VMware port.
314 .Bl -tag -width VMIO_SIOCSETMACADDR
315 .It Dv VMIO_SIOCSIFFLAGS