1.\" $NetBSD: tap.4,v 1.4 2005/01/10 22:35:01 wiz Exp $ 2.\" 3.\" Copyright (c) 2004, 2005 The NetBSD Foundation. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to the NetBSD Foundation 7.\" by Quentin Garnier. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd January 10, 2005 38.Dt TAP 4 39.Os 40.Sh NAME 41.Nm tap 42.Nd virtual Ethernet device 43.Sh SYNOPSIS 44.Cd pseudo-device tap 45.Sh DESCRIPTION 46The 47.Nm 48driver allows the creation and use of virtual Ethernet devices. 49Those interfaces appear just as any real Ethernet NIC to the kernel, 50but can also be accessed by userland through a character device node in order 51to read frames being sent by the system or to inject frames. 52.Pp 53In that respect it is very similar to what 54.Xr tun 4 55provides, but the added Ethernet layer allows easy integration with machine 56emulators or virtual Ethernet networks through the use of 57.Xr bridge 4 58with tunneling. 59.Ss INTERFACE CREATION 60Interfaces may be created in two different ways: 61using the 62.Xr ifconfig 8 63.Cm create 64command with a specified device number, 65or its 66.Xr ioctl 2 67equivalent, 68.Dv SIOCIFCREATE , 69or using the special cloning device 70.Pa /dev/tap . 71.Pp 72The former works the same as any other cloning network interface: 73the administrator can create and destroy interfaces at any time, 74notably at boot time. 75This is the easiest way of combining 76.Nm 77and 78.Xr bridge 4 . 79Later, userland will actually access the interfaces through the specific 80device nodes 81.Pa /dev/tapN . 82.Pp 83The latter is aimed at applications that need a virtual Ethernet device for 84the duration of their execution. 85A new interface is created at the opening of 86.Pa /dev/tap , 87and is later destroyed when the last process using the file descriptor closes 88it. 89.Ss CHARACTER DEVICES 90Whether the 91.Nm 92devices are accessed through the special cloning device 93.Pa /dev/tap 94or through the specific devices 95.Pa /dev/tapN , 96the possible actions to control the matching interface are the same. 97.Pp 98When using 99.Pa /dev/tap 100though, as the interface is created on-the-fly, its name is not known 101immediately by the application. 102Therefore the 103.Dv TAPGIFNAME 104ioctl is provided. 105It should be the first action an application using the special cloning device 106will do. 107It takes a pointer to a 108.Ft struct ifreq 109as an argument. 110.Pp 111Ethernet frames sent out by the kernel on a 112.Nm 113interface can be obtained by the controlling application with 114.Xr read 2 . 115It can also inject frames in the kernel with 116.Xr write 2 . 117There is absolutely no validation of the content of the injected frame, 118it can be any data, of any length. 119.Pp 120One call of 121.Xr write 2 122will inject a single frame in the kernel, as one call of 123.Xr read 2 124will retrieve a single frame from the queue, to the extent of the provided 125buffer. 126If the buffer is not large enough, the frame will be truncated. 127.Pp 128.Nm 129character devices support the 130.Dv FIONREAD 131ioctl which returns the size of the next available frame, 132or 0 if there is no available frame in the queue. 133.Pp 134They also support non-blocking I/O through the 135.Dv FIONBIO 136ioctl. 137In that mode, 138.Er EWOULDBLOCK 139is returned by 140.Xr read 2 141when no data is available. 142.Pp 143Asynchronous I/O is supported through the 144.Dv FIOASYNC , 145.Dv FIOSETOWN , 146and 147.Dv FIOGETOWN 148ioctls. 149The first will enable 150.Dv SIGIO 151generation, while the two other configure the process group that 152will receive the signal when data is ready. 153.Pp 154Synchronisation may also be achieved through the use of 155.Xr select 2 , 156.Xr poll 2 , 157or 158.Xr kevent 2 . 159.Ss ETHERNET ADDRESS 160When a 161.Nm 162device is created, it is assigned an Ethernet address 163of the form f0:0b:a4:xx:xx:xx. 164This address can later be changed in two ways: 165through a sysctl node, or an ioctl call. 166.Pp 167The sysctl node is net.link.tap.\*[Lt]iface\*[Gt]. 168Any string of six colon-separated hexadecimal numbers will be accepted. 169Reading that node will provide a string representation of the current 170Ethernet address. 171.Pp 172The address can also be changed with the 173.Dv SIOCSIFPHYADDR 174ioctl, which is used the same way as with 175.Xr gif 4 . 176The difference is in the family of the address which is passed inside the 177.Ft struct ifreqalias 178argument, which should be set to 179.Dv AF_LINK . 180This ioctl call should be made on a socket, as it is not available on 181the ioctl handler of the character device interface. 182.Sh FILES 183.Bl -tag -compact -width /dev/tap[0-9]* 184.It Pa /dev/tap 185cloning device 186.It Pa /dev/tap[0-9]* 187individual character device nodes 188.El 189.Sh SEE ALSO 190.Xr bridge 4 , 191.Xr gif 4 , 192.Xr tun 4 , 193.Xr ifconfig 8 194.Sh HISTORY 195The 196.Nm 197driver first appeared in 198.Nx 3.0 . 199