From: Aaron LI Date: Tue, 17 Jul 2018 11:04:12 +0000 (+0800) Subject: if_tun: Update tun.4 man page to match the code X-Git-Tag: v5.5.0~384 X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/commitdiff_plain/b24712baecd0d6a60456e438a12293241e320636 if_tun: Update tun.4 man page to match the code Mainly follow FreeBSD's tun.4, refer to NetBSD's tun.4, and with my own minor adjustments. --- diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4 index 643f9424a9..f74fedd7d0 100644 --- a/share/man/man4/tun.4 +++ b/share/man/man4/tun.4 @@ -1,9 +1,8 @@ .\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ .\" $FreeBSD: src/share/man/man4/tun.4,v 1.9.2.4 2001/08/17 13:08:39 ru Exp $ -.\" $DragonFly: src/share/man/man4/tun.4,v 1.3 2006/05/26 19:39:39 swildner Exp $ .\" Based on PR#2411 .\" -.Dd August 6, 2009 +.Dd July 17, 2018 .Dt TUN 4 .Os .Sh NAME @@ -36,16 +35,37 @@ or a terminal for and a character-special device .Dq control interface. +A client program transfers IP (by default) packets to or from the +.Nm +.Dq control +interface. +The +.Xr tap 4 +interface provides similar functionality at the Ethernet layer: +a client will transfer Ethernet frames to or from a +.Xr tap 4 +.Dq control +interface. .Pp The network interfaces are named .Dq Li tun0 , .Dq Li tun1 , -etc, and each one supports the usual network-interface -.Xr ioctl 2 Ns s , -such as -.Dv SIOCSIFADDR -and -.Dv SIOCSIFNETMASK , +etc., one for each control device that has been opened. +.Pp +The +.Nm +interface permits opens on the special control device +.Pa /dev/tun . +When this device is opened, +.Nm +will return a handle for the lowest unused +.Nm +device (use +.Xr devname 3 +to determine which). +.Pp +Each interface supports the usual network-interface +.Xr ioctl 2 Ns s and thus can be used with .Xr ifconfig 8 like any other interface. @@ -59,14 +79,13 @@ network interface, the packet can be read from the control device .Dq input there); writing a packet to the control device generates an input -packet on the network interface, as if the (non\-existent) +packet on the network interface, as if the (non-existent) hardware had just received it. .Pp -The tunnel device, normally -.Pa /dev/tun Ns Ar N , +The tunnel device +.Pq Pa /dev/tun Ns Ar N is exclusive-open -(it cannot be opened if it is already open) -and is restricted to the super-user. +(it cannot be opened if it is already open). A .Xr read 2 call will return an error @@ -86,15 +105,30 @@ If the packet is longer than is allowed for in the buffer passed to .Xr read 2 , the extra data will be silently dropped. .Pp -Packets can be optionally prepended with the destination address as presented -to the network interface output routine, +If the +.Dv TUNSLMODE +ioctl has been set (i.e., +.Dq link-layer +mode), packets read from the control device will be prepended +with the destination address as presented to the network interface output +routine, .Fn tunoutput . The destination address is in .Vt struct sockaddr format. The actual length of the prepended address is in the member .Va sa_len . -The packet data follows immediately. +If the +.Dv TUNSIFHEAD +ioctl has been set (i.e., +.Dq multi-af +mode), packets will be prepended with a 4-byte address +family in network byte order. +.Dv TUNSLMODE +and +.Dv TUNSIFHEAD +are mutually exclusive. +In any case, the packet data follows immediately. .Pp A .Xr write 2 @@ -105,24 +139,31 @@ Each .Xr write 2 call supplies exactly one packet; the packet length is taken from the amount of data provided to -.Xr write 2 . +.Xr write 2 +(minus any supplied address family). Writes will not block; if the packet cannot be accepted for a transient reason (e.g., no buffer space available), it is silently dropped; if the reason is not transient (e.g., packet too large), an error is returned. -If -.Dq link-layer mode -is on -(see +.Pp +If the .Dv TUNSLMODE -below), -the actual packet data must be preceded by a +ioctl has been set (i.e., +.Dq link-layer +mode), the actual packet data must be preceded by a .Vt struct sockaddr . The driver currently only inspects the .Va sa_family field. +If the +.Dv TUNSIFHEAD +ioctl has been set (i.e., +.Dq multi-af +mode), the address family must be prepended, otherwise the +packet is assumed to be of type +.Dv AF_INET . .Pp The following .Xr ioctl 2 @@ -159,25 +200,30 @@ The argument should be a pointer to an its value must be either .Dv IFF_POINTOPOINT or -.Dv IFF_BROADCAST . +.Dv IFF_BROADCAST +and should have +.Dv IFF_MULTICAST +OR'd into the value if multicast support is required. The type of the corresponding .Dq Li tun Ns Ar N interface is set to the supplied type. If the value is anything else, an .Er EINVAL -error occurs. +error is returned. The interface must be down at the time; if it is up, an .Er EBUSY -error occurs. +error is returned. .It Dv TUNSLMODE The argument should be a pointer to an .Vt int ; -a non-zero value turns on +a non-zero value turns off +.Dq multi-af +mode and turns on .Dq link-layer mode, causing packets read from the tunnel device to be prepended with -network destination address. +the network destination address (see above). .It Dv TUNSIFPID -Will set the pid owning the tunnel device to the current process's pid. +Will set the PID owning the tunnel device to the current process's PID. .It Dv TUNSIFHEAD The argument should be a pointer to an .Vt int ; @@ -185,18 +231,13 @@ a non-zero value turns off .Dq link-layer mode, and enables .Dq multi-af -mode, where every packet is preceded with a four byte address family. +mode, where every packet is preceded with a 4-byte address family. .It Dv TUNGIFHEAD The argument should be a pointer to an .Vt int ; -this stores one if the device is in +the ioctl sets the value to one if the device is in .Dq multi-af -mode, and zero otherwise in it. -.It Dv FIONBIO -Turn non-blocking I/O for reads off or on, according as the argument -.Vt int Ns 's -value is or isn't zero. -(Writes are always non-blocking.) +mode, and zero otherwise. .It Dv FIOASYNC Turn asynchronous I/O for reads (i.e., generation of @@ -204,7 +245,7 @@ Turn asynchronous I/O for reads when data is available to be read) off or on, according as the argument .Vt int Ns 's -value is or isn't zero. +value is or is not zero. .It Dv FIONREAD If any packets are queued to be read, store the size of the first one into the argument @@ -238,8 +279,11 @@ If the interface is up when the data device is not open output packets are always thrown away rather than letting them pile up. .Sh SEE ALSO +.Xr ioctl 2 , +.Xr devname 3 , .Xr inet 4 , -.Xr intro 4 +.Xr tap 4 , +.Xr ifconfig 8 .Sh AUTHORS This manual page was originally obtained from .Nx .