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