1.\" $FreeBSD: src/share/man/man4/tap.4,v 1.1.2.7 2002/04/16 23:59:28 trhodes Exp $ 2.\" Based on PR#2411 3.\" 4.Dd July 19, 2018 5.Dt TAP 4 6.Os 7.Sh NAME 8.Nm tap 9.Nd Ethernet tunnel software network interface 10.Sh SYNOPSIS 11.Cd pseudo-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.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 the 54.Pa if_tap.ko 55module is unloaded, or until removed with 56.Dq ifconfig destroy 57(see below). 58.Pp 59The 60.Nm 61devices are created using interface cloning. 62This is done using the 63.Dq ifconfig tap Ns Sy N No create 64command. 65This is the preferred method of creating 66.Nm 67devices. 68The same method allows removal of interfaces by using the 69.Dq ifconfig tap Ns Sy N No destroy 70command. 71.Pp 72The 73.Nm 74interface permits opens on the special control device 75.Pa /dev/tap . 76When this special device is opened, 77.Nm 78will return a handle for the lowest unused 79.Nm 80device (use 81.Xr devname 3 82to determine which). 83.Pp 84Control devices (once successfully opened) persist until the 85.Pa if_tap.ko 86module is unloaded or the interface is destroyed. 87.Pp 88Each interface supports the usual Ethernet network interface 89.Xr ioctl 2 Ns s 90and thus can be used with 91.Xr ifconfig 8 92like any other Ethernet interface. 93When the system chooses to transmit 94an Ethernet frame on the network interface, the frame can be read from 95the control device 96(it appears as 97.Dq input 98there); 99writing an Ethernet frame to the control device generates an input frame on 100the network interface, as if the 101(non-existent) 102hardware had just received it. 103.Pp 104The Ethernet tunnel device, normally 105.Pa /dev/tap Ns Sy N , 106is exclusive-open 107(it cannot be opened if it is already open) 108and is restricted to the super-user, unless the 109.Xr sysctl 8 110variable 111.Va net.link.tap.user_open 112is non-zero. 113If the 114.Xr sysctl 8 115variable 116.Va net.link.tap.up_on_open 117is non-zero, the tunnel device will be marked 118.Dq up 119when the control device is opened. 120A 121.Fn read 122call will return an error 123.Pq Er EHOSTDOWN 124if the interface is not 125.Dq ready . 126Once the interface is ready, 127.Fn read 128will return an Ethernet frame if one is available; if not, it will 129either block until one is or return 130.Er EWOULDBLOCK , 131depending on whether non-blocking I/O has been enabled. 132If the frame 133is longer than is allowed for in the buffer passed to 134.Fn read , 135the extra data will be silently dropped. 136.Pp 137A 138.Xr write 2 139call passes an Ethernet frame in to be 140.Dq received 141on the pseudo-interface. 142Each 143.Fn write 144call supplies exactly one frame; the frame length is taken from the 145amount of data provided to 146.Fn write . 147Writes will not block; if the frame cannot be accepted 148for a transient reason 149(e.g., no buffer space available), 150it is silently dropped; if the reason is not transient 151(e.g., frame too large), 152an error is returned. 153The following 154.Xr ioctl 2 155calls are supported 156(defined in 157.In net/tap/if_tap.h ) : 158.Bl -tag -width ".Dv TAPSIFINFO" 159.It Dv TAPSDEBUG 160The argument should be a pointer to an 161.Va int ; 162this sets the internal debugging variable to that value. 163What, if anything, this variable controls is not documented here, 164see the source code. 165.It Dv TAPGDEBUG 166The argument should be a pointer to an 167.Va int ; 168this stores the internal debugging variable's value into it. 169.It Dv TAPSIFINFO 170Set network interface information (line speed and MTU). 171The type must be the same as returned by 172.Dv TAPGIFINFO 173or set to 174.Dv IFT_ETHER , 175otherwise the 176.Xr ioctl 2 177call will fail. 178The argument should be a pointer to a 179.Va struct tapinfo . 180.It Dv TAPGIFINFO 181Retrieve network interface information (line speed, MTU and type). 182The argument should be a pointer to a 183.Va struct tapinfo . 184.It Dv TAPGIFNAME 185Retrieve network interface name. 186The argument should be a pointer to a 187.Va struct ifreq . 188The interface name will be returned in the 189.Va ifr_name 190field. 191.It Dv FIOASYNC 192Turn asynchronous I/O for reads 193(i.e., generation of 194.Dv SIGIO 195when data is available to be read) 196off or on, according as the argument 197.Va int Ns 's 198value is or is not zero. 199.It Dv FIONREAD 200If any frames are queued to be read, store the size of the first one into the argument 201.Va int ; 202otherwise, store zero. 203.It Dv TIOCSPGRP 204Set the process group to receive 205.Dv SIGIO 206signals, when asynchronous I/O is enabled, to the argument 207.Va int 208value. 209.It Dv TIOCGPGRP 210Retrieve the process group value for 211.Dv SIGIO 212signals into the argument 213.Va int 214value. 215.It Dv SIOCGIFFLAGS 216Retrieve the flags of the network interface associated with the control 217device into the argument 218.Va int 219value. 220.It Dv SIOCGIFADDR 221Retrieve the MAC address of the associated network interface. 222The argument should be a pointer to a 223.Va uint8_t 224array of length 225.Dv ETHER_ADDR_LEN . 226This command is used by the 227.Xr vke 4 228device. 229.It Dv SIOCSIFADDR 230Set the MAC address of the associated network interface. 231The argument should be a pointer to a 232.Va uint8_t 233array of length 234.Dv ETHER_ADDR_LEN . 235.El 236.Pp 237The control device also supports 238.Xr select 2 239for read; selecting for write is pointless, and always succeeds, since 240writes are always non-blocking. 241.Pp 242On the last close of the data device, the interface is 243brought down 244(as if with 245.Dq ifconfig tap Ns Sy N No down ) . 246All queued frames are thrown away. 247If the interface is up when the data 248device is not open, output frames are thrown away rather than 249letting them pile up. 250.Sh SEE ALSO 251.Xr inet 4 , 252.Xr tun 4 , 253.Xr vke 4 , 254.Xr ifconfig 8 255