1.\" Based on PR#2411 2.\" 3.Dd January 13, 2020 4.Dt TAP 4 5.Os 6.Sh NAME 7.Nm tap , 8.Nm vmnet 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 TAPSTRANSIENT 207The argument should be a pointer to an 208.Va int ; 209this sets the transient flag on 210the 211.Nm 212device. 213A transient 214.Nm 215will be destroyed upon last close. 216.It Dv TAPGTRANSIENT 217The argument should be a pointer to an 218.Va int ; 219this stores the current state (enabled or disabled) of the transient flag into 220it. 221.It Dv FIONBIO 222Turn non-blocking I/O for reads off or on, according as the argument 223.Va int Ns 's 224value is or is not zero 225(Writes are always nonblocking). 226.It Dv FIOASYNC 227Turn asynchronous I/O for reads 228(i.e., generation of 229.Dv SIGIO 230when data is available to be read) 231off or on, according as the argument 232.Va int Ns 's 233value is or is not zero. 234.It Dv FIONREAD 235If any frames are queued to be read, store the size of the first one into the argument 236.Va int ; 237otherwise, store zero. 238.It Dv TIOCSPGRP 239Set the process group to receive 240.Dv SIGIO 241signals, when asynchronous I/O is enabled, to the argument 242.Va int 243value. 244.It Dv TIOCGPGRP 245Retrieve the process group value for 246.Dv SIGIO 247signals into the argument 248.Va int 249value. 250.It Dv SIOCGIFADDR 251Retrieve the Media Access Control 252.Pq Dv MAC 253address of the 254.Dq remote 255side. 256This command is used by the VMware port and expected to be executed on 257descriptor, associated with control device 258(usually 259.Pa /dev/vmnet Ns Sy N 260or 261.Pa /dev/tap Ns Sy N ) . 262The 263.Va buffer , 264which is passed as the argument, is expected to have enough space to store 265the 266.Dv MAC 267address. 268At the open time both 269.Dq local 270and 271.Dq remote 272.Dv MAC 273addresses are the same, so this command could be used to retrieve the 274.Dq local 275.Dv MAC 276address. 277.It Dv SIOCSIFADDR 278Set the Media Access Control 279.Pq Dv MAC 280address of the 281.Dq remote 282side. 283This command is used by VMware port and expected to be executed on 284a descriptor, associated with control device 285(usually 286.Pa /dev/vmnet Ns Sy N ) . 287.El 288.Pp 289The control device also supports 290.Xr select 2 291for read; selecting for write is pointless, and always succeeds, since 292writes are always non-blocking. 293.Pp 294On the last close of the data device, the interface is 295brought down 296(as if with 297.Dq ifconfig tap Ns Sy N No down ) 298and has all of its configured addresses deleted 299unless the device is a 300.Em VMnet 301device, or has 302.Dv IFF_LINK0 303flag set. 304All queued frames are thrown away. 305If the interface is up when the data 306device is not open, output frames are thrown away rather than 307letting them pile up. 308.Pp 309The 310.Nm 311device can also be used with the VMware port as a replacement 312for the old 313.Em VMnet 314device driver. 315.Em VMnet 316devices do not 317.Xr ifconfig 8 318themselves down when the 319control device is closed. 320Everything else is the same. 321.Pp 322In addition to the above mentioned 323.Xr ioctl 2 324calls, there is an additional one for the VMware port. 325.Bl -tag -width VMIO_SIOCSETMACADDR 326.It Dv VMIO_SIOCSIFFLAGS 327VMware 328.Dv SIOCSIFFLAGS . 329.El 330.Sh SEE ALSO 331.Xr inet 4 , 332.Xr intro 4 , 333.Xr tun 4 334