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