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