10 .Nd Ethernet tunnel software network interface
16 interface is a software loopback mechanism that can be loosely
17 described as the network interface analog of the
21 does for network interfaces what the
23 driver does for terminals.
29 driver, provides two interfaces: an interface like the usual facility
31 (an Ethernet network interface in the case of
35 and a character-special device
38 A client program transfers Ethernet frames to or from the
44 interface provides similar functionality at the network layer:
45 a client will transfer IP (by default) packets to or from a
50 The network interfaces are named
53 etc., one for each control device that has been opened.
54 These Ethernet network interfaces persist until
56 module is unloaded, or until removed with "ifconfig destroy" (see below).
59 devices are created using interface cloning.
60 This is done using the
61 .Dq ifconfig tap Ns Sy N No create
63 This is the preferred method of creating
66 The same method allows removal of interfaces.
68 .Dq ifconfig tap Ns Sy N No destroy
74 .Va net.link.tap.devfs_cloning
78 permits opens on the special control device
80 When this device is opened,
82 will return a handle for the lowest unused
89 Disabling the legacy devfs cloning functionality may break existing
90 applications which use
96 It therefore defaults to being enabled until further notice.
99 Control devices (once successfully opened) persist until
101 is unloaded or the interface is destroyed.
103 Each interface supports the usual Ethernet network interface
105 and thus can be used with
107 like any other Ethernet interface.
108 When the system chooses to transmit
109 an Ethernet frame on the network interface, the frame can be read from
114 writing an Ethernet frame to the control device generates an input frame on
115 the network interface, as if the
117 hardware had just received it.
119 The Ethernet tunnel device, normally
120 .Pa /dev/tap Ns Sy N ,
122 (it cannot be opened if it is already open)
123 and is restricted to the super-user, unless the
126 .Va net.link.tap.user_open
131 .Va net.link.tap.up_on_open
132 is non-zero, the tunnel device will be marked
134 when the control device is opened.
137 call will return an error
139 if the interface is not
141 Once the interface is ready,
143 will return an Ethernet frame if one is available; if not, it will
144 either block until one is or return
146 depending on whether non-blocking I/O has been enabled.
148 is longer than is allowed for in the buffer passed to
150 the extra data will be silently dropped.
154 call passes an Ethernet frame in to be
156 on the pseudo-interface.
159 call supplies exactly one frame; the frame length is taken from the
160 amount of data provided to
162 Writes will not block; if the frame cannot be accepted
163 for a transient reason
164 (e.g., no buffer space available),
165 it is silently dropped; if the reason is not transient
166 (e.g., frame too large),
167 an error is returned.
173 .Bl -tag -width VMIO_SIOCSETMACADDR
175 Set network interface information (line speed and MTU).
176 The type must be the same as returned by
183 The argument should be a pointer to a
186 Retrieve network interface information (line speed, MTU and type).
187 The argument should be a pointer to a
190 The argument should be a pointer to an
192 this sets the internal debugging variable to that value.
194 anything, this variable controls is not documented here; see the source
197 The argument should be a pointer to an
199 this stores the internal debugging variable's value into it.
201 Retrieve network interface name.
202 The argument should be a pointer to a
204 The interface name will be returned in the
208 Turn non-blocking I/O for reads off or on, according as the argument
210 value is or is not zero
211 (Writes are always nonblocking).
213 Turn asynchronous I/O for reads
216 when data is available to be read)
217 off or on, according as the argument
219 value is or is not zero.
221 If any frames are queued to be read, store the size of the first one into the argument
223 otherwise, store zero.
225 Set the process group to receive
227 signals, when asynchronous I/O is enabled, to the argument
231 Retrieve the process group value for
233 signals into the argument
237 Retrieve the Media Access Control
242 This command is used by the VMware port and expected to be executed on
243 descriptor, associated with control device
245 .Pa /dev/vmnet Ns Sy N
247 .Pa /dev/tap Ns Sy N ) .
250 which is passed as the argument, is expected to have enough space to store
254 At the open time both
259 addresses are the same, so this command could be used to retrieve the
264 Set the Media Access Control
269 This command is used by VMware port and expected to be executed on
270 a descriptor, associated with control device
272 .Pa /dev/vmnet Ns Sy N ) .
275 The control device also supports
277 for read; selecting for write is pointless, and always succeeds, since
278 writes are always non-blocking.
280 On the last close of the data device, the interface is
283 .Dq ifconfig tap Ns Sy N No down )
284 and has all of its configured addresses deleted
285 unless the device is a
290 All queued frames are thrown away.
291 If the interface is up when the data
292 device is not open, output frames are thrown away rather than
293 letting them pile up.
297 device can also be used with the VMware port as a replacement
304 themselves down when the
305 control device is closed.
306 Everything else is the same.
308 In addition to the above mentioned
310 calls, there is an additional one for the VMware port.
311 .Bl -tag -width VMIO_SIOCSETMACADDR
312 .It Dv VMIO_SIOCSIFFLAGS