| @@ -1,189 +1,178 @@ | | | @@ -1,189 +1,178 @@ |
1 | .\" $NetBSD: tap.4,v 1.8.4.1 2009/03/18 05:15:48 snj Exp $ | | 1 | .\" $NetBSD: tap.4,v 1.8.4.2 2009/03/18 05:16:56 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 March 9, 2009 | | 27 | .Dd March 10, 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 |
36 | The | | 36 | The |
37 | .Nm | | 37 | .Nm |
38 | driver allows the creation and use of virtual Ethernet devices. | | 38 | driver allows the creation and use of virtual Ethernet devices. |
39 | Those interfaces appear just as any real Ethernet NIC to the kernel, | | 39 | Those interfaces appear just as any real Ethernet NIC to the kernel, |
40 | but can also be accessed by userland through a character device node in order | | 40 | but can also be accessed by userland through a character device node in order |
41 | to read frames being sent by the system or to inject frames. | | 41 | to read frames being sent by the system or to inject frames. |
42 | .Pp | | 42 | .Pp |
43 | In that respect it is very similar to what | | 43 | In that respect it is very similar to what |
44 | .Xr tun 4 | | 44 | .Xr tun 4 |
45 | provides, but the added Ethernet layer allows easy integration with machine | | 45 | provides, but the added Ethernet layer allows easy integration with machine |
46 | emulators or virtual Ethernet networks through the use of | | 46 | emulators or virtual Ethernet networks through the use of |
47 | .Xr bridge 4 | | 47 | .Xr bridge 4 |
48 | with tunneling. | | 48 | with tunneling. |
49 | .Ss INTERFACE CREATION | | 49 | .Ss INTERFACE CREATION |
50 | Interfaces may be created in two different ways: | | 50 | Interfaces may be created in two different ways: |
51 | using the | | 51 | using the |
52 | .Xr ifconfig 8 | | 52 | .Xr ifconfig 8 |
53 | .Cm create | | 53 | .Cm create |
54 | command with a specified device number, | | 54 | command with a specified device number, |
55 | or its | | 55 | or its |
56 | .Xr ioctl 2 | | 56 | .Xr ioctl 2 |
57 | equivalent, | | 57 | equivalent, |
58 | .Dv SIOCIFCREATE , | | 58 | .Dv SIOCIFCREATE , |
59 | or using the special cloning device | | 59 | or using the special cloning device |
60 | .Pa /dev/tap . | | 60 | .Pa /dev/tap . |
61 | .Pp | | 61 | .Pp |
62 | The former works the same as any other cloning network interface: | | 62 | The former works the same as any other cloning network interface: |
63 | the administrator can create and destroy interfaces at any time, | | 63 | the administrator can create and destroy interfaces at any time, |
64 | notably at boot time. | | 64 | notably at boot time. |
65 | This is the easiest way of combining | | 65 | This is the easiest way of combining |
66 | .Nm | | 66 | .Nm |
67 | and | | 67 | and |
68 | .Xr bridge 4 . | | 68 | .Xr bridge 4 . |
69 | Later, userland will actually access the interfaces through the specific | | 69 | Later, userland will actually access the interfaces through the specific |
70 | device nodes | | 70 | device nodes |
71 | .Pa /dev/tapN . | | 71 | .Pa /dev/tapN . |
72 | .Pp | | 72 | .Pp |
73 | The latter is aimed at applications that need a virtual Ethernet device for | | 73 | The latter is aimed at applications that need a virtual Ethernet device for |
74 | the duration of their execution. | | 74 | the duration of their execution. |
75 | A new interface is created at the opening of | | 75 | A new interface is created at the opening of |
76 | .Pa /dev/tap , | | 76 | .Pa /dev/tap , |
77 | and is later destroyed when the last process using the file descriptor closes | | 77 | and is later destroyed when the last process using the file descriptor closes |
78 | it. | | 78 | it. |
79 | .Ss CHARACTER DEVICES | | 79 | .Ss CHARACTER DEVICES |
80 | Whether the | | 80 | Whether the |
81 | .Nm | | 81 | .Nm |
82 | devices are accessed through the special cloning device | | 82 | devices are accessed through the special cloning device |
83 | .Pa /dev/tap | | 83 | .Pa /dev/tap |
84 | or through the specific devices | | 84 | or through the specific devices |
85 | .Pa /dev/tapN , | | 85 | .Pa /dev/tapN , |
86 | the possible actions to control the matching interface are the same. | | 86 | the possible actions to control the matching interface are the same. |
87 | .Pp | | 87 | .Pp |
88 | When using | | 88 | When using |
89 | .Pa /dev/tap | | 89 | .Pa /dev/tap |
90 | though, as the interface is created on-the-fly, its name is not known | | 90 | though, as the interface is created on-the-fly, its name is not known |
91 | immediately by the application. | | 91 | immediately by the application. |
92 | Therefore the | | 92 | Therefore the |
93 | .Dv TAPGIFNAME | | 93 | .Dv TAPGIFNAME |
94 | ioctl is provided. | | 94 | ioctl is provided. |
95 | It should be the first action an application using the special cloning device | | 95 | It should be the first action an application using the special cloning device |
96 | will do. | | 96 | will do. |
97 | It takes a pointer to a | | 97 | It takes a pointer to a |
98 | .Ft struct ifreq | | 98 | .Ft struct ifreq |
99 | as an argument. | | 99 | as an argument. |
100 | .Pp | | 100 | .Pp |
101 | Ethernet frames sent out by the kernel on a | | 101 | Ethernet frames sent out by the kernel on a |
102 | .Nm | | 102 | .Nm |
103 | interface can be obtained by the controlling application with | | 103 | interface can be obtained by the controlling application with |
104 | .Xr read 2 . | | 104 | .Xr read 2 . |
105 | It can also inject frames in the kernel with | | 105 | It can also inject frames in the kernel with |
106 | .Xr write 2 . | | 106 | .Xr write 2 . |
107 | There is absolutely no validation of the content of the injected frame, | | 107 | There is absolutely no validation of the content of the injected frame, |
108 | it can be any data, of any length. | | 108 | it can be any data, of any length. |
109 | .Pp | | 109 | .Pp |
110 | One call of | | 110 | One call of |
111 | .Xr write 2 | | 111 | .Xr write 2 |
112 | will inject a single frame in the kernel, as one call of | | 112 | will inject a single frame in the kernel, as one call of |
113 | .Xr read 2 | | 113 | .Xr read 2 |
114 | will retrieve a single frame from the queue, to the extent of the provided | | 114 | will retrieve a single frame from the queue, to the extent of the provided |
115 | buffer. | | 115 | buffer. |
116 | If the buffer is not large enough, the frame will be truncated. | | 116 | If the buffer is not large enough, the frame will be truncated. |
117 | .Pp | | 117 | .Pp |
118 | .Nm | | 118 | .Nm |
119 | character devices support the | | 119 | character devices support the |
120 | .Dv FIONREAD | | 120 | .Dv FIONREAD |
121 | ioctl which returns the size of the next available frame, | | 121 | ioctl which returns the size of the next available frame, |
122 | or 0 if there is no available frame in the queue. | | 122 | or 0 if there is no available frame in the queue. |
123 | .Pp | | 123 | .Pp |
124 | They also support non-blocking I/O through the | | 124 | They also support non-blocking I/O through the |
125 | .Dv FIONBIO | | 125 | .Dv FIONBIO |
126 | ioctl. | | 126 | ioctl. |
127 | In that mode, | | 127 | In that mode, |
128 | .Er EWOULDBLOCK | | 128 | .Er EWOULDBLOCK |
129 | is returned by | | 129 | is returned by |
130 | .Xr read 2 | | 130 | .Xr read 2 |
131 | when no data is available. | | 131 | when no data is available. |
132 | .Pp | | 132 | .Pp |
133 | Asynchronous I/O is supported through the | | 133 | Asynchronous I/O is supported through the |
134 | .Dv FIOASYNC , | | 134 | .Dv FIOASYNC , |
135 | .Dv FIOSETOWN , | | 135 | .Dv FIOSETOWN , |
136 | and | | 136 | and |
137 | .Dv FIOGETOWN | | 137 | .Dv FIOGETOWN |
138 | ioctls. | | 138 | ioctls. |
139 | The first will enable | | 139 | The first will enable |
140 | .Dv SIGIO | | 140 | .Dv SIGIO |
141 | generation, while the two other configure the process group that | | 141 | generation, while the two other configure the process group that |
142 | will receive the signal when data is ready. | | 142 | will receive the signal when data is ready. |
143 | .Pp | | 143 | .Pp |
144 | Synchronisation may also be achieved through the use of | | 144 | Synchronisation may also be achieved through the use of |
145 | .Xr select 2 , | | 145 | .Xr select 2 , |
146 | .Xr poll 2 , | | 146 | .Xr poll 2 , |
147 | or | | 147 | or |
148 | .Xr kevent 2 . | | 148 | .Xr kevent 2 . |
149 | .Ss ETHERNET ADDRESS | | 149 | .Ss ETHERNET ADDRESS |
150 | When a | | 150 | When a |
151 | .Nm | | 151 | .Nm |
152 | device is created, it is assigned an Ethernet address | | 152 | device is created, it is assigned an Ethernet address |
153 | of the form f2:0b:a4:xx:xx:xx. | | 153 | of the form f2:0b:a4:xx:xx:xx. |
154 | This address can later be changed in two ways: | | 154 | This address can later be changed using |
155 | through a sysctl node, or an ioctl call. | | 155 | .Xr ifconfig 8 |
156 | .Pp | | 156 | to add an active link layer address, or directly via the |
157 | The sysctl node is net.link.tap.\*[Lt]iface\*[Gt]. | | 157 | .Dv SIOCALIFADDR |
158 | Any string of six colon-separated hexadecimal numbers will be accepted. | | 158 | ioctl on a |
159 | Reading that node will provide a string representation of the current | | 159 | .Dv PF_LINK |
160 | Ethernet address. | | 160 | socket, as it is not available on |
161 | .Pp | | | |
162 | The address can also be changed with the | | | |
163 | .Dv SIOCSIFPHYADDR | | | |
164 | ioctl, which is used the same way as with | | | |
165 | .Xr gif 4 . | | | |
166 | The difference is in the family of the address which is passed inside the | | | |
167 | .Ft struct ifaliasreq | | | |
168 | argument, which should be set to | | | |
169 | .Dv AF_LINK . | | | |
170 | This ioctl call should be made on a socket, as it is not available on | | | |
171 | the ioctl handler of the character device interface. | | 161 | the ioctl handler of the character device interface. |
172 | .Sh FILES | | 162 | .Sh FILES |
173 | .Bl -tag -compact -width /dev/tap[0-9]* | | 163 | .Bl -tag -compact -width /dev/tap[0-9]* |
174 | .It Pa /dev/tap | | 164 | .It Pa /dev/tap |
175 | cloning device | | 165 | cloning device |
176 | .It Pa /dev/tap[0-9]* | | 166 | .It Pa /dev/tap[0-9]* |
177 | individual character device nodes | | 167 | individual character device nodes |
178 | .El | | 168 | .El |
179 | .Sh SEE ALSO | | 169 | .Sh SEE ALSO |
180 | .Xr bridge 4 , | | 170 | .Xr bridge 4 , |
181 | .Xr etherip 4 , | | 171 | .Xr etherip 4 , |
182 | .Xr gif 4 , | | | |
183 | .Xr tun 4 , | | 172 | .Xr tun 4 , |
184 | .Xr ifconfig 8 | | 173 | .Xr ifconfig 8 |
185 | .Sh HISTORY | | 174 | .Sh HISTORY |
186 | The | | 175 | The |
187 | .Nm | | 176 | .Nm |
188 | driver first appeared in | | 177 | driver first appeared in |
189 | .Nx 3.0 . | | 178 | .Nx 3.0 . |