1.\" $FreeBSD$ 2.\" Based on PR#2411 3.\" 4.Dd September 8, 2008 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 , 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 TAPSIFINFO 167Set network interface information (line speed, MTU and type). 168The argument should be a pointer to a 169.Va struct tapinfo . 170.It Dv TAPGIFINFO 171Retrieve network interface information (line speed, MTU and type). 172The argument should be a pointer to a 173.Va struct tapinfo . 174.It Dv TAPSDEBUG 175The argument should be a pointer to an 176.Va int ; 177this sets the internal debugging variable to that value. 178What, if 179anything, this variable controls is not documented here; see the source 180code. 181.It Dv TAPGDEBUG 182The argument should be a pointer to an 183.Va int ; 184this stores the internal debugging variable's value into it. 185.It Dv TAPGIFNAME 186Retrieve network interface name. 187The argument should be a pointer to a 188.Va struct ifreq . 189The interface name will be returned in the 190.Va ifr_name 191field. 192.It Dv FIONBIO 193Turn non-blocking I/O for reads off or on, according as the argument 194.Va int Ns 's 195value is or is not zero 196(Writes are always nonblocking). 197.It Dv FIOASYNC 198Turn asynchronous I/O for reads 199(i.e., generation of 200.Dv SIGIO 201when data is available to be read) 202off or on, according as the argument 203.Va int Ns 's 204value is or is not zero. 205.It Dv FIONREAD 206If any frames are queued to be read, store the size of the first one into the argument 207.Va int ; 208otherwise, store zero. 209.It Dv TIOCSPGRP 210Set the process group to receive 211.Dv SIGIO 212signals, when asynchronous I/O is enabled, to the argument 213.Va int 214value. 215.It Dv TIOCGPGRP 216Retrieve the process group value for 217.Dv SIGIO 218signals into the argument 219.Va int 220value. 221.It Dv SIOCGIFADDR 222Retrieve the Media Access Control 223.Pq Dv MAC 224address of the 225.Dq remote 226side. 227This command is used by the VMware port and expected to be executed on 228descriptor, associated with control device 229(usually 230.Pa /dev/vmnet Ns Sy N 231or 232.Pa /dev/tap Ns Sy N ) . 233The 234.Va buffer , 235which is passed as the argument, is expected to have enough space to store 236the 237.Dv MAC 238address. 239At the open time both 240.Dq local 241and 242.Dq remote 243.Dv MAC 244addresses are the same, so this command could be used to retrieve the 245.Dq local 246.Dv MAC 247address. 248.It Dv SIOCSIFADDR 249Set the Media Access Control 250.Pq Dv MAC 251address of the 252.Dq remote 253side. 254This command is used by VMware port and expected to be executed on 255a descriptor, associated with control device 256(usually 257.Pa /dev/vmnet Ns Sy N ) . 258.El 259.Pp 260The control device also supports 261.Xr select 2 262for read; selecting for write is pointless, and always succeeds, since 263writes are always non-blocking. 264.Pp 265On the last close of the data device, the interface is 266brought down 267(as if with 268.Dq ifconfig tap Ns Sy N No down ) 269unless the device is a 270.Em VMnet 271device. 272All queued frames are thrown away. 273If the interface is up when the data 274device is not open, output frames are thrown away rather than 275letting them pile up. 276.Pp 277The 278.Nm 279device can also be used with the VMware port as a replacement 280for the old 281.Em VMnet 282device driver. 283The driver uses the minor number 284to select between 285.Nm 286and 287.Nm vmnet 288devices. 289.Em VMnet 290minor numbers begin at 291.Va 0x800000 292+ 293.Va N ; 294where 295.Va N 296is a 297.Em VMnet 298unit number. 299In this case the control device is expected to be 300.Pa /dev/vmnet Ns Sy N , 301and the network interface will be 302.Sy vmnet Ns Ar N . 303Additionally, 304.Em VMnet 305devices do not 306.Xr ifconfig 8 307themselves down when the 308control device is closed. 309Everything else is the same. 310.Pp 311In addition to the above mentioned 312.Xr ioctl 2 313calls, there is an additional one for the VMware port. 314.Bl -tag -width VMIO_SIOCSETMACADDR 315.It Dv VMIO_SIOCSIFFLAGS 316VMware 317.Dv SIOCSIFFLAGS . 318.El 319.Sh SEE ALSO 320.Xr inet 4 , 321.Xr intro 4 322