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