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