Wed Mar 18 05:15:48 2009 UTC ()
Pull up following revision(s) (requested by plunky in ticket #571):
	share/man/man4/tap.4: revision 1.9
ifreqalias (non existent) -> ifaliasreq (the real deal)


(snj)
diff -r1.8 -r1.8.4.1 src/share/man/man4/tap.4
cvs diff -r1.8 -r1.8.4.1 src/share/man/man4/tap.4 (switch to unified diff)

--- src/share/man/man4/tap.4 2008/04/30 13:10:54 1.8
+++ src/share/man/man4/tap.4 2009/03/18 05:15:48 1.8.4.1
@@ -1,189 +1,189 @@ @@ -1,189 +1,189 @@
1.\" $NetBSD: tap.4,v 1.8 2008/04/30 13:10:54 martin Exp $ 1.\" $NetBSD: tap.4,v 1.8.4.1 2009/03/18 05:15:48 snj Exp $
2.\" 2.\"
3.\" Copyright (c) 2004, 2005 The NetBSD Foundation. 3.\" Copyright (c) 2004, 2005 The NetBSD Foundation.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25.\" POSSIBILITY OF SUCH DAMAGE. 25.\" POSSIBILITY OF SUCH DAMAGE.
26.\" 26.\"
27.Dd December 18, 2006 27.Dd March 9, 2009
28.Dt TAP 4 28.Dt TAP 4
29.Os 29.Os
30.Sh NAME 30.Sh NAME
31.Nm tap 31.Nm tap
32.Nd virtual Ethernet device 32.Nd virtual Ethernet device
33.Sh SYNOPSIS 33.Sh SYNOPSIS
34.Cd pseudo-device tap 34.Cd pseudo-device tap
35.Sh DESCRIPTION 35.Sh DESCRIPTION
36The 36The
37.Nm 37.Nm
38driver allows the creation and use of virtual Ethernet devices. 38driver allows the creation and use of virtual Ethernet devices.
39Those interfaces appear just as any real Ethernet NIC to the kernel, 39Those interfaces appear just as any real Ethernet NIC to the kernel,
40but can also be accessed by userland through a character device node in order 40but can also be accessed by userland through a character device node in order
41to read frames being sent by the system or to inject frames. 41to read frames being sent by the system or to inject frames.
42.Pp 42.Pp
43In that respect it is very similar to what 43In that respect it is very similar to what
44.Xr tun 4 44.Xr tun 4
45provides, but the added Ethernet layer allows easy integration with machine 45provides, but the added Ethernet layer allows easy integration with machine
46emulators or virtual Ethernet networks through the use of 46emulators or virtual Ethernet networks through the use of
47.Xr bridge 4 47.Xr bridge 4
48with tunneling. 48with tunneling.
49.Ss INTERFACE CREATION 49.Ss INTERFACE CREATION
50Interfaces may be created in two different ways: 50Interfaces may be created in two different ways:
51using the 51using the
52.Xr ifconfig 8 52.Xr ifconfig 8
53.Cm create 53.Cm create
54command with a specified device number, 54command with a specified device number,
55or its 55or its
56.Xr ioctl 2 56.Xr ioctl 2
57equivalent, 57equivalent,
58.Dv SIOCIFCREATE , 58.Dv SIOCIFCREATE ,
59or using the special cloning device 59or using the special cloning device
60.Pa /dev/tap . 60.Pa /dev/tap .
61.Pp 61.Pp
62The former works the same as any other cloning network interface: 62The former works the same as any other cloning network interface:
63the administrator can create and destroy interfaces at any time, 63the administrator can create and destroy interfaces at any time,
64notably at boot time. 64notably at boot time.
65This is the easiest way of combining 65This is the easiest way of combining
66.Nm 66.Nm
67and 67and
68.Xr bridge 4 . 68.Xr bridge 4 .
69Later, userland will actually access the interfaces through the specific 69Later, userland will actually access the interfaces through the specific
70device nodes 70device nodes
71.Pa /dev/tapN . 71.Pa /dev/tapN .
72.Pp 72.Pp
73The latter is aimed at applications that need a virtual Ethernet device for 73The latter is aimed at applications that need a virtual Ethernet device for
74the duration of their execution. 74the duration of their execution.
75A new interface is created at the opening of 75A new interface is created at the opening of
76.Pa /dev/tap , 76.Pa /dev/tap ,
77and is later destroyed when the last process using the file descriptor closes 77and is later destroyed when the last process using the file descriptor closes
78it. 78it.
79.Ss CHARACTER DEVICES 79.Ss CHARACTER DEVICES
80Whether the 80Whether the
81.Nm 81.Nm
82devices are accessed through the special cloning device 82devices are accessed through the special cloning device
83.Pa /dev/tap 83.Pa /dev/tap
84or through the specific devices 84or through the specific devices
85.Pa /dev/tapN , 85.Pa /dev/tapN ,
86the possible actions to control the matching interface are the same. 86the possible actions to control the matching interface are the same.
87.Pp 87.Pp
88When using 88When using
89.Pa /dev/tap 89.Pa /dev/tap
90though, as the interface is created on-the-fly, its name is not known 90though, as the interface is created on-the-fly, its name is not known
91immediately by the application. 91immediately by the application.
92Therefore the 92Therefore the
93.Dv TAPGIFNAME 93.Dv TAPGIFNAME
94ioctl is provided. 94ioctl is provided.
95It should be the first action an application using the special cloning device 95It should be the first action an application using the special cloning device
96will do. 96will do.
97It takes a pointer to a 97It takes a pointer to a
98.Ft struct ifreq 98.Ft struct ifreq
99as an argument. 99as an argument.
100.Pp 100.Pp
101Ethernet frames sent out by the kernel on a 101Ethernet frames sent out by the kernel on a
102.Nm 102.Nm
103interface can be obtained by the controlling application with 103interface can be obtained by the controlling application with
104.Xr read 2 . 104.Xr read 2 .
105It can also inject frames in the kernel with 105It can also inject frames in the kernel with
106.Xr write 2 . 106.Xr write 2 .
107There is absolutely no validation of the content of the injected frame, 107There is absolutely no validation of the content of the injected frame,
108it can be any data, of any length. 108it can be any data, of any length.
109.Pp 109.Pp
110One call of 110One call of
111.Xr write 2 111.Xr write 2
112will inject a single frame in the kernel, as one call of 112will inject a single frame in the kernel, as one call of
113.Xr read 2 113.Xr read 2
114will retrieve a single frame from the queue, to the extent of the provided 114will retrieve a single frame from the queue, to the extent of the provided
115buffer. 115buffer.
116If the buffer is not large enough, the frame will be truncated. 116If the buffer is not large enough, the frame will be truncated.
117.Pp 117.Pp
118.Nm 118.Nm
119character devices support the 119character devices support the
120.Dv FIONREAD 120.Dv FIONREAD
121ioctl which returns the size of the next available frame, 121ioctl which returns the size of the next available frame,
122or 0 if there is no available frame in the queue. 122or 0 if there is no available frame in the queue.
123.Pp 123.Pp
124They also support non-blocking I/O through the 124They also support non-blocking I/O through the
125.Dv FIONBIO 125.Dv FIONBIO
126ioctl. 126ioctl.
127In that mode, 127In that mode,
128.Er EWOULDBLOCK 128.Er EWOULDBLOCK
129is returned by 129is returned by
130.Xr read 2 130.Xr read 2
131when no data is available. 131when no data is available.
132.Pp 132.Pp
133Asynchronous I/O is supported through the 133Asynchronous I/O is supported through the
134.Dv FIOASYNC , 134.Dv FIOASYNC ,
135.Dv FIOSETOWN , 135.Dv FIOSETOWN ,
136and 136and
137.Dv FIOGETOWN 137.Dv FIOGETOWN
138ioctls. 138ioctls.
139The first will enable 139The first will enable
140.Dv SIGIO 140.Dv SIGIO
141generation, while the two other configure the process group that 141generation, while the two other configure the process group that
142will receive the signal when data is ready. 142will receive the signal when data is ready.
143.Pp 143.Pp
144Synchronisation may also be achieved through the use of 144Synchronisation may also be achieved through the use of
145.Xr select 2 , 145.Xr select 2 ,
146.Xr poll 2 , 146.Xr poll 2 ,
147or 147or
148.Xr kevent 2 . 148.Xr kevent 2 .
149.Ss ETHERNET ADDRESS 149.Ss ETHERNET ADDRESS
150When a 150When a
151.Nm 151.Nm
152device is created, it is assigned an Ethernet address 152device is created, it is assigned an Ethernet address
153of the form f2:0b:a4:xx:xx:xx. 153of the form f2:0b:a4:xx:xx:xx.
154This address can later be changed in two ways: 154This address can later be changed in two ways:
155through a sysctl node, or an ioctl call. 155through a sysctl node, or an ioctl call.
156.Pp 156.Pp
157The sysctl node is net.link.tap.\*[Lt]iface\*[Gt]. 157The sysctl node is net.link.tap.\*[Lt]iface\*[Gt].
158Any string of six colon-separated hexadecimal numbers will be accepted. 158Any string of six colon-separated hexadecimal numbers will be accepted.
159Reading that node will provide a string representation of the current 159Reading that node will provide a string representation of the current
160Ethernet address. 160Ethernet address.
161.Pp 161.Pp
162The address can also be changed with the 162The address can also be changed with the
163.Dv SIOCSIFPHYADDR 163.Dv SIOCSIFPHYADDR
164ioctl, which is used the same way as with 164ioctl, which is used the same way as with
165.Xr gif 4 . 165.Xr gif 4 .
166The difference is in the family of the address which is passed inside the 166The difference is in the family of the address which is passed inside the
167.Ft struct ifreqalias 167.Ft struct ifaliasreq
168argument, which should be set to 168argument, which should be set to
169.Dv AF_LINK . 169.Dv AF_LINK .
170This ioctl call should be made on a socket, as it is not available on 170This ioctl call should be made on a socket, as it is not available on
171the ioctl handler of the character device interface. 171the ioctl handler of the character device interface.
172.Sh FILES 172.Sh FILES
173.Bl -tag -compact -width /dev/tap[0-9]* 173.Bl -tag -compact -width /dev/tap[0-9]*
174.It Pa /dev/tap 174.It Pa /dev/tap
175cloning device 175cloning device
176.It Pa /dev/tap[0-9]* 176.It Pa /dev/tap[0-9]*
177individual character device nodes 177individual character device nodes
178.El 178.El
179.Sh SEE ALSO 179.Sh SEE ALSO
180.Xr bridge 4 , 180.Xr bridge 4 ,
181.Xr etherip 4 , 181.Xr etherip 4 ,
182.Xr gif 4 , 182.Xr gif 4 ,
183.Xr tun 4 , 183.Xr tun 4 ,
184.Xr ifconfig 8 184.Xr ifconfig 8
185.Sh HISTORY 185.Sh HISTORY
186The 186The
187.Nm 187.Nm
188driver first appeared in 188driver first appeared in
189.Nx 3.0 . 189.Nx 3.0 .