1.\" $FreeBSD: src/share/man/man4/tap.4,v 1.1.2.7 2002/04/16 23:59:28 trhodes Exp $ 2.\" $DragonFly: src/share/man/man4/tap.4,v 1.6 2006/10/14 23:46:23 swildner Exp $ 3.\" Based on PR#2411 4.\" 5.Dd August 6, 2009 6.Os 7.Dt TAP 4 8.Sh NAME 9.Nm tap 10.Nd Ethernet tunnel software network interface 11.Sh SYNOPSIS 12.Cd pseudo-device tap 13.Sh DESCRIPTION 14The 15.Nm 16interface is a software loopback mechanism that can be loosely 17described as the network interface analog of the 18.Xr pty 4 , 19that is, 20.Nm 21does for network interfaces what the 22.Nm pty 23driver does for terminals. 24.Pp 25The 26.Nm 27driver, like the 28.Nm pty 29driver, provides two interfaces: an interface like the usual facility 30it is simulating 31(an Ethernet network interface in the case of 32.Nm , 33or a terminal for 34.Nm pty ) , 35and a character-special device 36.Dq control 37interface. 38.Pp 39The network interfaces are named 40.Sy tap Ns Ar 0 , 41.Sy tap Ns Ar 1 , 42etc, and each one supports the usual Ethernet network-interface 43.Xr ioctl 2 Ns s , 44such as 45.Dv SIOCSIFADDR 46and 47.Dv SIOCSIFNETMASK , 48and thus can be used with 49.Xr ifconfig 8 50like any other Ethernet interface. When the system chooses to transmit 51an Ethernet frame on the network interface, the frame can be read from 52the control device 53(it appears as 54.Dq input 55there); 56writing an Ethernet frame to the control device generates an input frame on 57the network interface, as if the 58(non-existent) 59hardware had just received it. 60.Pp 61The Ethernet tunnel device, normally 62.Pa /dev/tap Ns Sy N , 63is exclusive-open 64(it cannot be opened if it is already open) 65and is restricted to the super-user. 66A 67.Fn read 68call will return an error 69.Pq Er EHOSTDOWN 70if the interface is not 71.Dq ready . 72Once the interface is ready, 73.Fn read 74will return an Ethernet frame if one is available; if not, it will 75either block until one is or return 76.Er EWOULDBLOCK , 77depending on whether non-blocking I/O has been enabled. If the frame 78is longer than is allowed for in the buffer passed to 79.Fn read , 80the extra data will be silently dropped. 81.Pp 82A 83.Xr write 2 84call passes an Ethernet frame in to be 85.Dq received 86on the pseudo-interface. Each 87.Fn write 88call supplies exactly one frame; the frame length is taken from the 89amount of data provided to 90.Fn write . 91Writes will not block; if the frame cannot be accepted 92for a transient reason 93(e.g., no buffer space available), 94it is silently dropped; if the reason is not transient 95(e.g., frame too large), 96an error is returned. 97The following 98.Xr ioctl 2 99calls are supported 100(defined in 101.In net/tap/if_tap.h ) : 102.Bl -tag -width ".Dv VMIO_SIOCSETMACADDR" 103.It Dv TAPSDEBUG 104The argument should be a pointer to an 105.Va int ; 106this sets the internal debugging variable to that value. What, if 107anything, this variable controls is not documented here; see the source 108code. 109.It Dv TAPGDEBUG 110The argument should be a pointer to an 111.Va int ; 112this stores the internal debugging variable's value into it. 113.It Dv FIONBIO 114Turn non-blocking I/O for reads off or on, according as the argument 115.Va int Ns 's 116value is or isn't zero 117(Writes are always nonblocking). 118.It Dv FIOASYNC 119Turn asynchronous I/O for reads 120(i.e., generation of 121.Dv SIGIO 122when data is available to be read) 123off or on, according as the argument 124.Va int Ns 's 125value is or isn't zero. 126.It Dv FIONREAD 127If any frames are queued to be read, store the size of the first one into the argument 128.Va int ; 129otherwise, store zero. 130.It Dv TIOCSPGRP 131Set the process group to receive 132.Dv SIGIO 133signals, when asynchronous I/O is enabled, to the argument 134.Va int 135value. 136.It Dv TIOCGPGRP 137Retrieve the process group value for 138.Dv SIGIO 139signals into the argument 140.Va int 141value. 142.It Dv SIOCGIFADDR 143Retrieve the Media Access Control 144.Pq Dv MAC 145address of the 146.Dq remote 147side. This command is used by the VMware port and expected to be executed on 148descriptor, associated with control device 149(usually 150.Pa /dev/vmnet Ns Sy N 151or 152.Pa /dev/tap Ns Sy N ) . 153The 154.Va buffer , 155which is passed as the argument, is expected to have enough space to store 156the 157.Dv MAC 158address. At the open time both 159.Dq local 160and 161.Dq remote 162.Dv MAC 163addresses are the same, so this command could be used to retrieve the 164.Dq local 165.Dv MAC 166address. 167.It Dv SIOCSIFADDR 168Set the Media Access Control 169.Pq Dv MAC 170address of the 171.Dq remote 172side. This command is used by VMware port and expected to be executed on 173a descriptor, associated with control device 174(usually 175.Pa /dev/vmnet Ns Sy N ) . 176.El 177.Pp 178The control device also supports 179.Xr select 2 180for read; selecting for write is pointless, and always succeeds, since 181writes are always non-blocking. 182.Pp 183On the last close of the data device, the interface is 184brought down 185(as if with 186.Dq ifconfig tap Ns Sy N No down ) 187unless the devices is a 188.Em VMnet 189device. 190All queued frames are thrown away. If the interface is up when the data 191device is not open, output frames are thrown away rather than 192letting them pile up. 193.Pp 194The 195.Nm 196device is also can be used with the 197.Em VMware 198port as a replacement 199for the old 200.Em VMnet 201device driver. The driver uses the minor number 202to select between 203.Nm 204and 205.Nm vmnet 206devices. 207.Em VMnet 208minor numbers begin at 209.Va 0x10000 210+ 211.Va N ; 212where 213.Va N 214is a 215.Em VMnet 216unit number. In this case control device is expected to be 217.Pa /dev/vmnet Ns Sy N , 218and network interface will be 219.Sy vmnet Ns Ar N . 220Additionally, 221.Em VMnet 222devices do not 223.Xr ifconfig 8 224themselves down when the 225control device is closed. Everything else is the same. 226.Pp 227In addition to the above mentioned, 228.Xr ioctl 2 229calls, there is one additional one for the VMware port. 230.Bl -tag -width ".Dv VMIO_SIOCSETMACADDR" 231.It Dv VMIO_SIOCSIFFLAGS 232VMware 233.Dv SIOCSIFFLAGS . 234.El 235.Sh SEE ALSO 236.Xr inet 4 , 237.Xr intro 4 238