1.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ 2.\" $Id: tun.4,v 1.2 1997/09/07 12:29:55 joerg 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 Op Ar count 13.Sh DESCRIPTION 14The 15.Nm tun 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 tun 21does for network interfaces what the 22.Nm pty 23driver does for terminals. 24.Pp 25The 26.Nm tun 27driver, like the 28.Nm pty 29driver, provides two interfaces: an interface like the usual facility 30it is simulating 31.Po 32a network interface in the case of 33.Nm tun , 34or a terminal for 35.Nm pty Pc , 36and a character-special device 37.Dq control 38interface. 39.Pp 40The network interfaces are named 41.Sy tun Ns Ar 0 , 42.Sy tun Ns Ar 1 , 43etc, as many in all as the 44.Ar count 45figure given on the 46.Sy pseudo-device 47line. Each one supports the usual network-interface 48.Xr ioctl 2 Ns s , 49such as 50.Dv SIOCSIFADDR 51and 52.Dv SIOCSIFNETMASK , 53and thus can be used with 54.Xr ifconfig 8 55like any other interface. At boot time, they are 56.Dv POINTOPOINT 57interfaces, but this can be changed; see the description of the control 58device, below. When the system chooses to transmit a packet on the 59network interface, the packet can be read from the control device 60.Po 61it appears as 62.Dq input 63there 64.Pc ; 65writing a packet to the control device generates an input 66packet on the network interface, as if the 67.Pq non-existent 68hardware had just received it. 69.Pp 70The tunnel device, normally 71.Pa /dev/tun Ns Sy N , 72is exclusive-open 73.Po 74it cannot be opened if it is already open 75.Pc 76and is restricted to the super-user. A 77.Fn read 78call will return an error 79.Pq Er EHOSTDOWN 80if the interface is not 81.Dq ready 82.Po 83which means that the control device is open and the interface's 84address has been set 85.Pc . 86Once the interface is ready, 87.Fn read 88will return a packet if one is available; if not, it will either block 89until one is or return 90.Er EWOULDBLOCK , 91depending on whether non-blocking I/O has been enabled. If the packet 92is longer than is allowed for in the buffer passed to 93.Fn read , 94the extra data will be silently dropped. 95.Pp 96Packets can be optionally prepended with the destination address as presented 97to the network interface output routine 98.Pq Sq Li tunoutput . 99The destination address is in 100.Sq Li struct sockaddr 101format. The actual length of the prepended address is in the member 102.Sq Li sa_len . 103The packet data follows immediately. 104A 105.Xr write 2 106call passes a packet in to be 107.Dq received 108on the pseudo-interface. Each 109.Fn write 110call supplies exactly one packet; the packet length is taken from the 111amount of data provided to 112.Fn write . 113Writes will not block; if the packet cannot be accepted for a 114transient reason 115.Pq e.g., no buffer space available , 116it is silently dropped; if the reason is not transient 117.Pq e.g., packet too large , 118an error is returned. 119If 120.Dq link-layer mode 121is on 122.Pq see Dv TUNSLMODE No below , 123the actual packet data must be preceded by a 124.Sq Li struct sockaddr . 125The driver currently only inspects the 126.Sq Li sa_family 127field. 128The following 129.Xr ioctl 2 130calls are supported 131.Pq defined in Aq Pa net/if_tun.h Ns : 132.Bl -tag -width TUNSIFMODE 133.It Dv TUNSDEBUG 134The argument should be a pointer to an 135.Va int ; 136this sets the internal debugging variable to that value. What, if 137anything, this variable controls is not documented here; see the source 138code. 139.It Dv TUNGDEBUG 140The argument should be a pointer to an 141.Va int ; 142this stores the internal debugging variable's value into it. 143.It Dv TUNSIFMODE 144The argument should be a pointer to an 145.Va int ; 146its value must be 147.Dv IFF_POINTOPOINT 148or 149.Dv IFF_BROADCAST . 150The type of the corresponding 151.Em tun Ns Sy n 152interface is set to the supplied type. If the value is anything else, 153an 154.Er EINVAL 155error occurs. The interface must be down at the time; if it is up, an 156.Er EBUSY 157error occurs. 158.It Dv TUNSLMODE 159The argument should be a pointer to an 160.Va int ; 161a non-zero value turns on 162.Dq link-layer 163mode, causing packets read from the tunnel device to be prepended with 164network destination address. 165.It Dv FIONBIO 166Turn non-blocking I/O for reads off or on, according as the argument 167.Va int Ns 's 168value is or isn't zero 169.Pq Writes are always nonblocking . 170.It Dv FIOASYNC 171Turn asynchronous I/O for reads 172.Po 173i.e., generation of 174.Dv SIGIO 175when data is available to be read 176.Pc off or on, according as the argument 177.Va int Ns 's 178value is or isn't zero. 179.It Dv FIONREAD 180If any packets are queued to be read, store the size of the first one 181into the argument 182.Va int ; 183otherwise, store zero. 184.It Dv TIOCSPGRP 185Set the process group to receive 186.Dv SIGIO 187signals, when asynchronous I/O is enabled, to the argument 188.Va int 189value. 190.It Dv TIOCGPGRP 191Retrieve the process group value for 192.Dv SIGIO 193signals into the argument 194.Va int 195value. 196.El 197.Pp 198The control device also supports 199.Xr select 2 200for read; selecting for write is pointless, and always succeeds, since 201writes are always non-blocking. 202.Pp 203On the last close of the data device, by default, the interface is 204brought down 205.Po as if with 206.Dq ifconfig tun Ns Sy n No down 207.Pc . 208All queued packets are thrown away. 209.Po If the interface is up when the data device is not open 210output packets are always 211thrown away rather than letting them pile up 212.Pc . 213.Sh SEE ALSO 214.Xr inet 4 , 215.Xr intro 4 216.Sh BUGS 217Currently is IP-only. 218.Sh AUTHORS 219This man page has been obtained from 220.Em NetBSD . 221