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