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
93 and thus can be used with
95 like any other Ethernet interface.
96 When the system chooses to transmit
97 an Ethernet frame on the network interface, the frame can be read from
102 writing an Ethernet frame to the control device generates an input frame on
103 the network interface, as if the
105 hardware had just received it.
107 The Ethernet tunnel device, normally
108 .Pa /dev/tap Ns Sy N ,
110 (it cannot be opened if it is already open)
111 and is restricted to the super-user, unless the
114 .Va net.link.tap.user_open
119 .Va net.link.tap.up_on_open
120 is non-zero, the tunnel device will be marked
122 when the control device is opened.
125 call will return an error
127 if the interface is not
129 Once the interface is ready,
131 will return an Ethernet frame if one is available; if not, it will
132 either block until one is or return
134 depending on whether non-blocking I/O has been enabled.
136 is longer than is allowed for in the buffer passed to
138 the extra data will be silently dropped.
142 call passes an Ethernet frame in to be
144 on the pseudo-interface.
147 call supplies exactly one frame; the frame length is taken from the
148 amount of data provided to
150 Writes will not block; if the frame cannot be accepted
151 for a transient reason
152 (e.g., no buffer space available),
153 it is silently dropped; if the reason is not transient
154 (e.g., frame too large),
155 an error is returned.
161 .Bl -tag -width VMIO_SIOCSETMACADDR
163 Set network interface information (line speed, MTU and type).
164 The argument should be a pointer to a
167 Retrieve network interface information (line speed, MTU and type).
168 The argument should be a pointer to a
171 The argument should be a pointer to an
173 this sets the internal debugging variable to that value.
175 anything, this variable controls is not documented here; see the source
178 The argument should be a pointer to an
180 this stores the internal debugging variable's value into it.
182 Retrieve network interface name.
183 The argument should be a pointer to a
185 The interface name will be returned in the
189 Turn non-blocking I/O for reads off or on, according as the argument
191 value is or is not zero
192 (Writes are always nonblocking).
194 Turn asynchronous I/O for reads
197 when data is available to be read)
198 off or on, according as the argument
200 value is or is not zero.
202 If any frames are queued to be read, store the size of the first one into the argument
204 otherwise, store zero.
206 Set the process group to receive
208 signals, when asynchronous I/O is enabled, to the argument
212 Retrieve the process group value for
214 signals into the argument
218 Retrieve the Media Access Control
223 This command is used by the VMware port and expected to be executed on
224 descriptor, associated with control device
226 .Pa /dev/vmnet Ns Sy N
228 .Pa /dev/tap Ns Sy N ) .
231 which is passed as the argument, is expected to have enough space to store
235 At the open time both
240 addresses are the same, so this command could be used to retrieve the
245 Set the Media Access Control
250 This command is used by VMware port and expected to be executed on
251 a descriptor, associated with control device
253 .Pa /dev/vmnet Ns Sy N ) .
256 The control device also supports
258 for read; selecting for write is pointless, and always succeeds, since
259 writes are always non-blocking.
261 On the last close of the data device, the interface is
264 .Dq ifconfig tap Ns Sy N No down )
265 unless the device is a
268 All queued frames are thrown away.
269 If the interface is up when the data
270 device is not open, output frames are thrown away rather than
271 letting them pile up.
275 device can also be used with the VMware port as a replacement
279 The driver uses the minor number
286 minor numbers begin at
295 In this case the control device is expected to be
296 .Pa /dev/vmnet Ns Sy N ,
297 and the network interface will be
303 themselves down when the
304 control device is closed.
305 Everything else is the same.
307 In addition to the above mentioned
309 calls, there is an additional one for the VMware port.
310 .Bl -tag -width VMIO_SIOCSETMACADDR
311 .It Dv VMIO_SIOCSIFFLAGS