1.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ 2.\" $FreeBSD: src/share/man/man4/tun.4,v 1.9.2.4 2001/08/17 13:08:39 ru Exp $ 3.\" Based on PR#2411 4.\" 5.Dd March 10, 1996 6.Dt TUN 4 7.Os 8.Sh NAME 9.Nm tun 10.Nd tunnel software network interface 11.Sh SYNOPSIS 12.Cd pseudo-device tun 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(a 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. 38.Pp 39The network interfaces are named 40.Dq Li tun0 , 41.Dq Li tun1 , 42etc, as many as were made by 43.Xr MAKEDEV 8 . 44Each one supports the usual network-interface 45.Xr ioctl 2 Ns s , 46such as 47.Dv SIOCSIFADDR 48and 49.Dv SIOCSIFNETMASK , 50and thus can be used with 51.Xr ifconfig 8 52like any other interface. 53At boot time, they are 54.Dv POINTOPOINT 55interfaces, but this can be changed; see the description of the control 56device, below. 57When the system chooses to transmit a packet on the 58network interface, the packet can be read from the control device 59(it appears as 60.Dq input 61there); 62writing a packet to the control device generates an input 63packet on the network interface, as if the (non\-existent) 64hardware had just received it. 65.Pp 66The tunnel device, normally 67.Pa /dev/tun Ns Ar N , 68is exclusive-open 69(it cannot be opened if it is already open) 70and is restricted to the super-user. 71A 72.Xr read 2 73call will return an error 74.Pq Er EHOSTDOWN 75if the interface is not 76.Dq ready 77(which means that the control device is open and the interface's 78address has been set). 79.Pp 80Once the interface is ready, 81.Xr read 2 82will return a packet if one is available; if not, it will either block 83until one is or return 84.Er EWOULDBLOCK , 85depending on whether non-blocking I/O has been enabled. 86If the packet is longer than is allowed for in the buffer passed to 87.Xr read 2 , 88the extra data will be silently dropped. 89.Pp 90Packets can be optionally prepended with the destination address as presented 91to the network interface output routine, 92.Fn tunoutput . 93The destination address is in 94.Vt struct sockaddr 95format. 96The actual length of the prepended address is in the member 97.Va sa_len . 98The packet data follows immediately. 99.Pp 100A 101.Xr write 2 102call passes a packet in to be 103.Dq received 104on the pseudo-interface. 105Each 106.Xr write 2 107call supplies exactly one packet; the packet length is taken from the 108amount of data provided to 109.Xr write 2 . 110Writes will not block; if the packet cannot be accepted for a 111transient reason 112(e.g., no buffer space available), 113it is silently dropped; if the reason is not transient 114(e.g., packet too large), 115an error is returned. 116If 117.Dq link-layer mode 118is on 119(see 120.Dv TUNSLMODE 121below), 122the actual packet data must be preceded by a 123.Vt struct sockaddr . 124The driver currently only inspects the 125.Va sa_family 126field. 127.Pp 128The following 129.Xr ioctl 2 130calls are supported 131(defined in 132.Aq Pa net/if_tun.h ) : 133.Bl -tag -width ".Dv TUNSIFMODE" 134.It Dv TUNSDEBUG 135The argument should be a pointer to an 136.Vt int ; 137this sets the internal debugging variable to that value. 138What, if anything, this variable controls is not documented here; see 139the source code. 140.It Dv TUNGDEBUG 141The argument should be a pointer to an 142.Vt int ; 143this stores the internal debugging variable's value into it. 144.It Dv TUNSIFINFO 145The argument should be a pointer to an 146.Vt struct tuninfo 147and allows setting the MTU, the type, and the baudrate of the tunnel 148device. 149The 150.Vt struct tuninfo 151is declared in 152.Aq Pa net/if_tun.h . 153.It Dv TUNGIFINFO 154The argument should be a pointer to an 155.Vt struct tuninfo , 156where the current MTU, type, and baudrate will be stored. 157.It Dv TUNSIFMODE 158The argument should be a pointer to an 159.Vt int ; 160its value must be either 161.Dv IFF_POINTOPOINT 162or 163.Dv IFF_BROADCAST . 164The type of the corresponding 165.Dq Li tun Ns Ar N 166interface is set to the supplied type. 167If the value is anything else, an 168.Er EINVAL 169error occurs. 170The interface must be down at the time; if it is up, an 171.Er EBUSY 172error occurs. 173.It Dv TUNSLMODE 174The argument should be a pointer to an 175.Vt int ; 176a non-zero value turns on 177.Dq link-layer 178mode, causing packets read from the tunnel device to be prepended with 179network destination address. 180.It Dv TUNSIFPID 181Will set the pid owning the tunnel device to the current process's pid. 182.It Dv TUNSIFHEAD 183The argument should be a pointer to an 184.Vt int ; 185a non-zero value turns off 186.Dq link-layer 187mode, and enables 188.Dq multi-af 189mode, where every packet is preceded with a four byte address family. 190.It Dv TUNGIFHEAD 191The argument should be a pointer to an 192.Vt int ; 193this stores one if the device is in 194.Dq multi-af 195mode, and zero otherwise in it. 196.It Dv FIONBIO 197Turn non-blocking I/O for reads off or on, according as the argument 198.Vt int Ns 's 199value is or isn't zero. 200(Writes are always non-blocking.) 201.It Dv FIOASYNC 202Turn asynchronous I/O for reads 203(i.e., generation of 204.Dv SIGIO 205when data is available to be read) 206off or on, according as the argument 207.Vt int Ns 's 208value is or isn't zero. 209.It Dv FIONREAD 210If any packets are queued to be read, store the size of the first one 211into the argument 212.Vt int ; 213otherwise, store zero. 214.It Dv TIOCSPGRP 215Set the process group to receive 216.Dv SIGIO 217signals, when asynchronous I/O is enabled, to the argument 218.Vt int 219value. 220.It Dv TIOCGPGRP 221Retrieve the process group value for 222.Dv SIGIO 223signals into the argument 224.Vt int 225value. 226.El 227.Pp 228The control device also supports 229.Xr select 2 230for read; selecting for write is pointless, and always succeeds, since 231writes are always non-blocking. 232.Pp 233On the last close of the data device, by default, the interface is 234brought down 235(as if with 236.Nm ifconfig Ar tunN Cm down ) . 237All queued packets are thrown away. 238If the interface is up when the data device is not open 239output packets are always thrown away rather than letting 240them pile up. 241.Sh SEE ALSO 242.Xr inet 4 , 243.Xr intro 4 244.Sh AUTHORS 245This manual page was originally obtained from 246.Nx . 247