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