1.\" $FreeBSD$ 2.\" Based on PR#2411 3.\" 4.Dd April 29, 2019 5.Dt TAP 4 6.Os 7.Sh NAME 8.Nm tap 9.Nd Ethernet tunnel software network interface 10.Sh SYNOPSIS 11.Cd device tuntap 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.Xr pty 4 22driver does for terminals. 23.Pp 24The 25.Nm 26driver, like the 27.Xr pty 4 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.Xr pty 4 ) , 34and a character-special device 35.Dq control 36interface. 37A client program transfers Ethernet frames to or from the 38.Nm 39.Dq control 40interface. 41The 42.Xr tun 4 43interface provides similar functionality at the network layer: 44a client will transfer IP (by default) packets to or from a 45.Xr tun 4 46.Dq control 47interface. 48.Pp 49The network interfaces are named 50.Dq Li tap0 , 51.Dq Li tap1 , 52etc., one for each control device that has been opened. 53These Ethernet network interfaces persist until 54.Pa if_tuntap.ko 55module is unloaded, or until removed with "ifconfig destroy" (see below). 56.Pp 57.Nm 58devices are created using interface cloning. 59This is done using the 60.Dq ifconfig tap Ns Sy N No create 61command. 62This is the preferred method of creating 63.Nm 64devices. 65The same method allows removal of interfaces. 66For this, use the 67.Dq ifconfig tap Ns Sy N No destroy 68command. 69.Pp 70If the 71.Xr sysctl 8 72variable 73.Va net.link.tap.devfs_cloning 74is non-zero, the 75.Nm 76interface 77permits opens on the special control device 78.Pa /dev/tap . 79When this device is opened, 80.Nm 81will return a handle for the lowest unused 82.Nm 83device (use 84.Xr devname 3 85to determine which). 86.Pp 87.Bf Em 88Disabling the legacy devfs cloning functionality may break existing 89applications which use 90.Nm , 91such as 92.Tn VMware 93and 94.Xr ssh 1 . 95It therefore defaults to being enabled until further notice. 96.Ef 97.Pp 98Control devices (once successfully opened) persist until 99.Pa if_tuntap.ko 100is unloaded or the interface is destroyed. 101.Pp 102Each interface supports the usual Ethernet network interface 103.Xr ioctl 2 Ns s 104and thus can be used with 105.Xr ifconfig 8 106like any other Ethernet interface. 107When the system chooses to transmit 108an Ethernet frame on the network interface, the frame can be read from 109the control device 110(it appears as 111.Dq input 112there); 113writing an Ethernet frame to the control device generates an input frame on 114the network interface, as if the 115(non-existent) 116hardware had just received it. 117.Pp 118The Ethernet tunnel device, normally 119.Pa /dev/tap Ns Sy N , 120is exclusive-open 121(it cannot be opened if it is already open) 122and is restricted to the super-user, unless the 123.Xr sysctl 8 124variable 125.Va net.link.tap.user_open 126is non-zero. 127If the 128.Xr sysctl 8 129variable 130.Va net.link.tap.up_on_open 131is non-zero, the tunnel device will be marked 132.Dq up 133when the control device is opened. 134A 135.Fn read 136call will return an error 137.Pq Er EHOSTDOWN 138if the interface is not 139.Dq ready . 140Once the interface is ready, 141.Fn read 142will return an Ethernet frame if one is available; if not, it will 143either block until one is or return 144.Er EWOULDBLOCK , 145depending on whether non-blocking I/O has been enabled. 146If the frame 147is longer than is allowed for in the buffer passed to 148.Fn read , 149the extra data will be silently dropped. 150.Pp 151A 152.Xr write 2 153call passes an Ethernet frame in to be 154.Dq received 155on the pseudo-interface. 156Each 157.Fn write 158call supplies exactly one frame; the frame length is taken from the 159amount of data provided to 160.Fn write . 161Writes will not block; if the frame cannot be accepted 162for a transient reason 163(e.g., no buffer space available), 164it is silently dropped; if the reason is not transient 165(e.g., frame too large), 166an error is returned. 167The following 168.Xr ioctl 2 169calls are supported 170(defined in 171.In net/if_tap.h ) : 172.Bl -tag -width VMIO_SIOCSETMACADDR 173.It Dv TAPSIFINFO 174Set network interface information (line speed and MTU). 175The type must be the same as returned by 176.Dv TAPGIFINFO 177or set to 178.Dv IFT_ETHER 179else the 180.Xr ioctl 2 181call will fail. 182The argument should be a pointer to a 183.Va struct tapinfo . 184.It Dv TAPGIFINFO 185Retrieve network interface information (line speed, MTU and type). 186The argument should be a pointer to a 187.Va struct tapinfo . 188.It Dv TAPSDEBUG 189The argument should be a pointer to an 190.Va int ; 191this sets the internal debugging variable to that value. 192What, if 193anything, this variable controls is not documented here; see the source 194code. 195.It Dv TAPGDEBUG 196The argument should be a pointer to an 197.Va int ; 198this stores the internal debugging variable's value into it. 199.It Dv TAPGIFNAME 200Retrieve network interface name. 201The argument should be a pointer to a 202.Va struct ifreq . 203The interface name will be returned in the 204.Va ifr_name 205field. 206.It Dv FIONBIO 207Turn non-blocking I/O for reads off or on, according as the argument 208.Va int Ns 's 209value is or is not zero 210(Writes are always nonblocking). 211.It Dv FIOASYNC 212Turn asynchronous I/O for reads 213(i.e., generation of 214.Dv SIGIO 215when data is available to be read) 216off or on, according as the argument 217.Va int Ns 's 218value is or is not zero. 219.It Dv FIONREAD 220If any frames are queued to be read, store the size of the first one into the argument 221.Va int ; 222otherwise, store zero. 223.It Dv TIOCSPGRP 224Set the process group to receive 225.Dv SIGIO 226signals, when asynchronous I/O is enabled, to the argument 227.Va int 228value. 229.It Dv TIOCGPGRP 230Retrieve the process group value for 231.Dv SIGIO 232signals into the argument 233.Va int 234value. 235.It Dv SIOCGIFADDR 236Retrieve the Media Access Control 237.Pq Dv MAC 238address of the 239.Dq remote 240side. 241This command is used by the VMware port and expected to be executed on 242descriptor, associated with control device 243(usually 244.Pa /dev/vmnet Ns Sy N 245or 246.Pa /dev/tap Ns Sy N ) . 247The 248.Va buffer , 249which is passed as the argument, is expected to have enough space to store 250the 251.Dv MAC 252address. 253At the open time both 254.Dq local 255and 256.Dq remote 257.Dv MAC 258addresses are the same, so this command could be used to retrieve the 259.Dq local 260.Dv MAC 261address. 262.It Dv SIOCSIFADDR 263Set the Media Access Control 264.Pq Dv MAC 265address of the 266.Dq remote 267side. 268This command is used by VMware port and expected to be executed on 269a descriptor, associated with control device 270(usually 271.Pa /dev/vmnet Ns Sy N ) . 272.El 273.Pp 274The control device also supports 275.Xr select 2 276for read; selecting for write is pointless, and always succeeds, since 277writes are always non-blocking. 278.Pp 279On the last close of the data device, the interface is 280brought down 281(as if with 282.Dq ifconfig tap Ns Sy N No down ) 283unless the device is a 284.Em VMnet 285device, or has 286.Dv IFF_LINK0 287flag set. 288All queued frames are thrown away. 289If the interface is up when the data 290device is not open, output frames are thrown away rather than 291letting them pile up. 292.Pp 293The 294.Nm 295device can also be used with the VMware port as a replacement 296for the old 297.Em VMnet 298device driver. 299.Em VMnet 300devices do not 301.Xr ifconfig 8 302themselves down when the 303control device is closed. 304Everything else is the same. 305.Pp 306In addition to the above mentioned 307.Xr ioctl 2 308calls, there is an additional one for the VMware port. 309.Bl -tag -width VMIO_SIOCSETMACADDR 310.It Dv VMIO_SIOCSIFFLAGS 311VMware 312.Dv SIOCSIFFLAGS . 313.El 314.Sh SEE ALSO 315.Xr inet 4 , 316.Xr intro 4 , 317.Xr tun 4 318