1.\" $FreeBSD$ 2.\" Based on PR#2411 3.\" 4.Dd January 26, 2012 5.Dt TAP 4 6.Os 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 93and thus can be used with 94.Xr ifconfig 8 95like any other Ethernet interface. 96When the system chooses to transmit 97an Ethernet frame on the network interface, the frame can be read from 98the control device 99(it appears as 100.Dq input 101there); 102writing an Ethernet frame to the control device generates an input frame on 103the network interface, as if the 104(non-existent) 105hardware had just received it. 106.Pp 107The Ethernet tunnel device, normally 108.Pa /dev/tap Ns Sy N , 109is exclusive-open 110(it cannot be opened if it is already open) 111and is restricted to the super-user, unless the 112.Xr sysctl 8 113variable 114.Va net.link.tap.user_open 115is non-zero. 116If the 117.Xr sysctl 8 118variable 119.Va net.link.tap.up_on_open 120is non-zero, the tunnel device will be marked 121.Dq up 122when the control device is opened. 123A 124.Fn read 125call will return an error 126.Pq Er EHOSTDOWN 127if the interface is not 128.Dq ready . 129Once the interface is ready, 130.Fn read 131will return an Ethernet frame if one is available; if not, it will 132either block until one is or return 133.Er EWOULDBLOCK , 134depending on whether non-blocking I/O has been enabled. 135If the frame 136is longer than is allowed for in the buffer passed to 137.Fn read , 138the extra data will be silently dropped. 139.Pp 140A 141.Xr write 2 142call passes an Ethernet frame in to be 143.Dq received 144on the pseudo-interface. 145Each 146.Fn write 147call supplies exactly one frame; the frame length is taken from the 148amount of data provided to 149.Fn write . 150Writes will not block; if the frame cannot be accepted 151for a transient reason 152(e.g., no buffer space available), 153it is silently dropped; if the reason is not transient 154(e.g., frame too large), 155an error is returned. 156The following 157.Xr ioctl 2 158calls are supported 159(defined in 160.In net/if_tap.h ) : 161.Bl -tag -width VMIO_SIOCSETMACADDR 162.It Dv TAPSIFINFO 163Set network interface information (line speed, MTU and type). 164The argument should be a pointer to a 165.Va struct tapinfo . 166.It Dv TAPGIFINFO 167Retrieve network interface information (line speed, MTU and type). 168The argument should be a pointer to a 169.Va struct tapinfo . 170.It Dv TAPSDEBUG 171The argument should be a pointer to an 172.Va int ; 173this sets the internal debugging variable to that value. 174What, if 175anything, this variable controls is not documented here; see the source 176code. 177.It Dv TAPGDEBUG 178The argument should be a pointer to an 179.Va int ; 180this stores the internal debugging variable's value into it. 181.It Dv TAPGIFNAME 182Retrieve network interface name. 183The argument should be a pointer to a 184.Va struct ifreq . 185The interface name will be returned in the 186.Va ifr_name 187field. 188.It Dv FIONBIO 189Turn non-blocking I/O for reads off or on, according as the argument 190.Va int Ns 's 191value is or is not zero 192(Writes are always nonblocking). 193.It Dv FIOASYNC 194Turn asynchronous I/O for reads 195(i.e., generation of 196.Dv SIGIO 197when data is available to be read) 198off or on, according as the argument 199.Va int Ns 's 200value is or is not zero. 201.It Dv FIONREAD 202If any frames are queued to be read, store the size of the first one into the argument 203.Va int ; 204otherwise, store zero. 205.It Dv TIOCSPGRP 206Set the process group to receive 207.Dv SIGIO 208signals, when asynchronous I/O is enabled, to the argument 209.Va int 210value. 211.It Dv TIOCGPGRP 212Retrieve the process group value for 213.Dv SIGIO 214signals into the argument 215.Va int 216value. 217.It Dv SIOCGIFADDR 218Retrieve the Media Access Control 219.Pq Dv MAC 220address of the 221.Dq remote 222side. 223This command is used by the VMware port and expected to be executed on 224descriptor, associated with control device 225(usually 226.Pa /dev/vmnet Ns Sy N 227or 228.Pa /dev/tap Ns Sy N ) . 229The 230.Va buffer , 231which is passed as the argument, is expected to have enough space to store 232the 233.Dv MAC 234address. 235At the open time both 236.Dq local 237and 238.Dq remote 239.Dv MAC 240addresses are the same, so this command could be used to retrieve the 241.Dq local 242.Dv MAC 243address. 244.It Dv SIOCSIFADDR 245Set the Media Access Control 246.Pq Dv MAC 247address of the 248.Dq remote 249side. 250This command is used by VMware port and expected to be executed on 251a descriptor, associated with control device 252(usually 253.Pa /dev/vmnet Ns Sy N ) . 254.El 255.Pp 256The control device also supports 257.Xr select 2 258for read; selecting for write is pointless, and always succeeds, since 259writes are always non-blocking. 260.Pp 261On the last close of the data device, the interface is 262brought down 263(as if with 264.Dq ifconfig tap Ns Sy N No down ) 265unless the device is a 266.Em VMnet 267device. 268All queued frames are thrown away. 269If the interface is up when the data 270device is not open, output frames are thrown away rather than 271letting them pile up. 272.Pp 273The 274.Nm 275device can also be used with the VMware port as a replacement 276for the old 277.Em VMnet 278device driver. 279The driver uses the minor number 280to select between 281.Nm 282and 283.Nm vmnet 284devices. 285.Em VMnet 286minor numbers begin at 287.Va 0x800000 288+ 289.Va N ; 290where 291.Va N 292is a 293.Em VMnet 294unit number. 295In this case the control device is expected to be 296.Pa /dev/vmnet Ns Sy N , 297and the network interface will be 298.Sy vmnet Ns Ar N . 299Additionally, 300.Em VMnet 301devices do not 302.Xr ifconfig 8 303themselves down when the 304control device is closed. 305Everything else is the same. 306.Pp 307In addition to the above mentioned 308.Xr ioctl 2 309calls, there is an additional one for the VMware port. 310.Bl -tag -width VMIO_SIOCSETMACADDR 311.It Dv VMIO_SIOCSIFFLAGS 312VMware 313.Dv SIOCSIFFLAGS . 314.El 315.Sh SEE ALSO 316.Xr inet 4 , 317.Xr intro 4 318