1.\" $FreeBSD: src/share/man/man4/tap.4,v 1.1.2.7 2002/04/16 23:59:28 trhodes Exp $ 2.\" Based on PR#2411 3.\" 4.Dd August 6, 2009 5.Dt TAP 4 6.Os 7.Sh NAME 8.Nm tap 9.Nd Ethernet tunnel software network interface 10.Sh SYNOPSIS 11.Cd pseudo-device tap 12.Sh DESCRIPTION 13The 14.Nm 15interface is a software loopback mechanism that can be loosely 16described as the network interface analog of the 17.Xr pty 4 , 18that is, 19.Nm 20does for network interfaces what the 21.Nm pty 22driver does for terminals. 23.Pp 24The 25.Nm 26driver, like the 27.Nm pty 28driver, provides two interfaces: an interface like the usual facility 29it is simulating 30(an Ethernet network interface in the case of 31.Nm , 32or a terminal for 33.Nm pty ) , 34and a character-special device 35.Dq control 36interface. 37.Pp 38The network interfaces are named 39.Sy tap Ns Ar 0 , 40.Sy tap Ns Ar 1 , 41etc, and each one supports the usual Ethernet network-interface 42.Xr ioctl 2 Ns s , 43such as 44.Dv SIOCSIFADDR 45and 46.Dv SIOCSIFNETMASK , 47and thus can be used with 48.Xr ifconfig 8 49like any other Ethernet interface. When the system chooses to transmit 50an Ethernet frame on the network interface, the frame can be read from 51the control device 52(it appears as 53.Dq input 54there); 55writing an Ethernet frame to the control device generates an input frame on 56the network interface, as if the 57(non-existent) 58hardware had just received it. 59.Pp 60The Ethernet tunnel device, normally 61.Pa /dev/tap Ns Sy N , 62is exclusive-open 63(it cannot be opened if it is already open) 64and is restricted to the super-user. 65A 66.Fn read 67call will return an error 68.Pq Er EHOSTDOWN 69if the interface is not 70.Dq ready . 71Once the interface is ready, 72.Fn read 73will return an Ethernet frame if one is available; if not, it will 74either block until one is or return 75.Er EWOULDBLOCK , 76depending on whether non-blocking I/O has been enabled. If the frame 77is longer than is allowed for in the buffer passed to 78.Fn read , 79the extra data will be silently dropped. 80.Pp 81A 82.Xr write 2 83call passes an Ethernet frame in to be 84.Dq received 85on the pseudo-interface. Each 86.Fn write 87call supplies exactly one frame; the frame length is taken from the 88amount of data provided to 89.Fn write . 90Writes will not block; if the frame cannot be accepted 91for a transient reason 92(e.g., no buffer space available), 93it is silently dropped; if the reason is not transient 94(e.g., frame too large), 95an error is returned. 96The following 97.Xr ioctl 2 98calls are supported 99(defined in 100.In net/tap/if_tap.h ) : 101.Bl -tag -width ".Dv VMIO_SIOCSETMACADDR" 102.It Dv TAPSDEBUG 103The argument should be a pointer to an 104.Va int ; 105this sets the internal debugging variable to that value. What, if 106anything, this variable controls is not documented here; see the source 107code. 108.It Dv TAPGDEBUG 109The argument should be a pointer to an 110.Va int ; 111this stores the internal debugging variable's value into it. 112.It Dv FIONBIO 113Turn non-blocking I/O for reads off or on, according as the argument 114.Va int Ns 's 115value is or isn't zero 116(Writes are always nonblocking). 117.It Dv FIOASYNC 118Turn asynchronous I/O for reads 119(i.e., generation of 120.Dv SIGIO 121when data is available to be read) 122off or on, according as the argument 123.Va int Ns 's 124value is or isn't zero. 125.It Dv FIONREAD 126If any frames are queued to be read, store the size of the first one into the argument 127.Va int ; 128otherwise, store zero. 129.It Dv TIOCSPGRP 130Set the process group to receive 131.Dv SIGIO 132signals, when asynchronous I/O is enabled, to the argument 133.Va int 134value. 135.It Dv TIOCGPGRP 136Retrieve the process group value for 137.Dv SIGIO 138signals into the argument 139.Va int 140value. 141.It Dv SIOCGIFADDR 142Retrieve the Media Access Control 143.Pq Dv MAC 144address of the 145.Dq remote 146side. This command is used by the VMware port and expected to be executed on 147descriptor, associated with control device 148(usually 149.Pa /dev/vmnet Ns Sy N 150or 151.Pa /dev/tap Ns Sy N ) . 152The 153.Va buffer , 154which is passed as the argument, is expected to have enough space to store 155the 156.Dv MAC 157address. At the open time both 158.Dq local 159and 160.Dq remote 161.Dv MAC 162addresses are the same, so this command could be used to retrieve the 163.Dq local 164.Dv MAC 165address. 166.It Dv SIOCSIFADDR 167Set the Media Access Control 168.Pq Dv MAC 169address of the 170.Dq remote 171side. This command is used by VMware port and expected to be executed on 172a descriptor, associated with control device 173(usually 174.Pa /dev/vmnet Ns Sy N ) . 175.El 176.Pp 177The control device also supports 178.Xr select 2 179for read; selecting for write is pointless, and always succeeds, since 180writes are always non-blocking. 181.Pp 182On the last close of the data device, the interface is 183brought down 184(as if with 185.Dq ifconfig tap Ns Sy N No down ) 186unless the devices is a 187.Em VMnet 188device. 189All queued frames are thrown away. If the interface is up when the data 190device is not open, output frames are thrown away rather than 191letting them pile up. 192.Pp 193The 194.Nm 195device is also can be used with the 196.Em VMware 197port as a replacement 198for the old 199.Em VMnet 200device driver. The driver uses the minor number 201to select between 202.Nm 203and 204.Nm vmnet 205devices. 206.Em VMnet 207minor numbers begin at 208.Va 0x10000 209+ 210.Va N ; 211where 212.Va N 213is a 214.Em VMnet 215unit number. In this case control device is expected to be 216.Pa /dev/vmnet Ns Sy N , 217and network interface will be 218.Sy vmnet Ns Ar N . 219Additionally, 220.Em VMnet 221devices do not 222.Xr ifconfig 8 223themselves down when the 224control device is closed. Everything else is the same. 225.Pp 226In addition to the above mentioned, 227.Xr ioctl 2 228calls, there is one additional one for the VMware port. 229.Bl -tag -width ".Dv VMIO_SIOCSETMACADDR" 230.It Dv VMIO_SIOCSIFFLAGS 231VMware 232.Dv SIOCSIFFLAGS . 233.El 234.Sh SEE ALSO 235.Xr inet 4 , 236.Xr intro 4 237