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