1.\" $FreeBSD$ 2.\" Based on PR#2411 3.\" 4.Dd July 9, 2000 5.Os 6.Dt TAP 4 7.Sh NAME 8.Nm tap 9.Nd Ethernet tunnel software network interface 10.Sh SYNOPSIS 11.Cd 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.Dq Li tap0 , 40.Dq Li tap1 , 41etc., one for each control device that has been opened. 42These Ethernet network interfaces persist until 43.Pa if_tap.ko 44module is unloaded (if 45.Nm 46is built into your kernel, the network interfaces cannot be removed). 47.Pp 48On older systems without 49.Xr devfs 5 50support, 51.Xr MAKEDEV 8 52should be used to create the initial control devices and the task 53of locating an unused device is left up to the opener (a 54.Nm 55device is usually obtained by attempting to open 56.Pa /dev/tap0 , 57and if that fails 58.Pa /dev/tap1 59etc., until an 60.Va errno 61of 62.Er EBUSY 63is not received). 64.Pp 65On systems with 66.Xr devfs 5 67support, 68.Nm 69permits opens on the special control device 70.Pa /dev/tap . 71When this device is opened, 72.Nm 73will return a handle for the lowest unused 74.Nm 75device (use 76.Xr devname 3 77to determine which). 78Control devices (once successfully opened) persist until 79.Pa if_tap.ko 80is unloaded in the same way that network interfaces persist (see above). 81.Pp 82Each interface supports the usual Ethernet network interface 83.Xr ioctl 2 Ns s , 84such as 85.Dv SIOCSIFADDR 86and 87.Dv SIOCSIFNETMASK , 88and thus can be used with 89.Xr ifconfig 8 90like any other Ethernet interface. 91When the system chooses to transmit 92an Ethernet frame on the network interface, the frame can be read from 93the control device 94(it appears as 95.Dq input 96there); 97writing an Ethernet frame to the control device generates an input frame on 98the network interface, as if the 99(non-existent) 100hardware had just received it. 101.Pp 102The Ethernet tunnel device, normally 103.Pa /dev/tap Ns Sy N , 104is exclusive-open 105(it cannot be opened if it is already open) 106and is restricted to the super-user. 107A 108.Fn read 109call will return an error 110.Pq Er EHOSTDOWN 111if the interface is not 112.Dq ready . 113Once the interface is ready, 114.Fn read 115will return an Ethernet frame if one is available; if not, it will 116either block until one is or return 117.Er EWOULDBLOCK , 118depending on whether non-blocking I/O has been enabled. 119If the frame 120is longer than is allowed for in the buffer passed to 121.Fn read , 122the extra data will be silently dropped. 123.Pp 124A 125.Xr write 2 126call passes an Ethernet frame in to be 127.Dq received 128on the pseudo-interface. 129Each 130.Fn write 131call supplies exactly one frame; the frame length is taken from the 132amount of data provided to 133.Fn write . 134Writes will not block; if the frame cannot be accepted 135for a transient reason 136(e.g., no buffer space available), 137it is silently dropped; if the reason is not transient 138(e.g., frame too large), 139an error is returned. 140The following 141.Xr ioctl 2 142calls are supported 143(defined in 144.Aq Pa net/if_tap.h ) : 145.Bl -tag -width VMIO_SIOCSETMACADDR 146.It Dv TAPSDEBUG 147The argument should be a pointer to an 148.Va int ; 149this sets the internal debugging variable to that value. 150What, if 151anything, this variable controls is not documented here; see the source 152code. 153.It Dv TAPGDEBUG 154The argument should be a pointer to an 155.Va int ; 156this stores the internal debugging variable's value into it. 157.It Dv FIONBIO 158Turn non-blocking I/O for reads off or on, according as the argument 159.Va int Ns 's 160value is or isn't zero 161(Writes are always nonblocking). 162.It Dv FIOASYNC 163Turn asynchronous I/O for reads 164(i.e., generation of 165.Dv SIGIO 166when data is available to be read) 167off or on, according as the argument 168.Va int Ns 's 169value is or isn't zero. 170.It Dv FIONREAD 171If any frames are queued to be read, store the size of the first one into the argument 172.Va int ; 173otherwise, store zero. 174.It Dv TIOCSPGRP 175Set the process group to receive 176.Dv SIGIO 177signals, when asynchronous I/O is enabled, to the argument 178.Va int 179value. 180.It Dv TIOCGPGRP 181Retrieve the process group value for 182.Dv SIGIO 183signals into the argument 184.Va int 185value. 186.It Dv SIOCGIFADDR 187Retrieve the Media Access Control 188.Pq Dv MAC 189address of the 190.Dq remote 191side. 192This command is used by the VMware port and expected to be executed on 193descriptor, associated with control device 194(usually 195.Pa /dev/vmnet Ns Sy N 196or 197.Pa /dev/tap Ns Sy N ) . 198The 199.Va buffer , 200which is passed as the argument, is expected to have enough space to store 201the 202.Dv MAC 203address. 204At the open time both 205.Dq local 206and 207.Dq remote 208.Dv MAC 209addresses are the same, so this command could be used to retrieve the 210.Dq local 211.Dv MAC 212address. 213.It Dv SIOCSIFADDR 214Set the Media Access Control 215.Pq Dv MAC 216address of the 217.Dq remote 218side. 219This command is used by VMware port and expected to be executed on 220a descriptor, associated with control device 221(usually 222.Pa /dev/vmnet Ns Sy N ) . 223.El 224.Pp 225The control device also supports 226.Xr select 2 227for read; selecting for write is pointless, and always succeeds, since 228writes are always non-blocking. 229.Pp 230On the last close of the data device, the interface is 231brought down 232(as if with 233.Dq ifconfig tap Ns Sy N No down ) 234unless the device is a 235.Em VMnet 236device. 237All queued frames are thrown away. 238If the interface is up when the data 239device is not open, output frames are thrown away rather than 240letting them pile up. 241.Pp 242The 243.Nm 244device can also be used with the VMware port as a replacement 245for the old 246.Em VMnet 247device driver. 248The driver uses the minor number 249to select between 250.Nm 251and 252.Nm vmnet 253devices. 254.Em VMnet 255minor numbers begin at 256.Va 0x800000 257+ 258.Va N ; 259where 260.Va N 261is a 262.Em VMnet 263unit number. 264In this case the control device is expected to be 265.Pa /dev/vmnet Ns Sy N , 266and the network interface will be 267.Sy vmnet Ns Ar N . 268Additionally, 269.Em VMnet 270devices do not 271.Xr ifconfig 8 272themselves down when the 273control device is closed. 274Everything else is the same. 275.Pp 276In addition to the above mentioned 277.Xr ioctl 2 278calls, there is an additional one for the VMware port. 279.Bl -tag -width VMIO_SIOCSETMACADDR 280.It Dv VMIO_SIOCSIFFLAGS 281VMware 282.Dv SIOCSIFFLAGS . 283.El 284.Sh SEE ALSO 285.Xr inet 4 , 286.Xr intro 4 287