Commit | Line | Data |
---|---|---|
984263bc | 1 | .\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ |
984263bc MD |
2 | .\" |
3 | .\" Copyright 1998 (c) The NetBSD Foundation, Inc. | |
4 | .\" All rights reserved. | |
5 | .\" | |
6 | .\" This code is derived from software contributed to The NetBSD Foundation | |
7 | .\" by Heiko W.Rupp <hwr@pilhuhn.de> | |
8 | .\" | |
9 | .\" Redistribution and use in source and binary forms, with or without | |
10 | .\" modification, are permitted provided that the following conditions | |
11 | .\" are met: | |
12 | .\" 1. Redistributions of source code must retain the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer. | |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
15 | .\" notice, this list of conditions and the following disclaimer in the | |
16 | .\" documentation and/or other materials provided with the distribution. | |
17 | .\" 3. All advertising materials mentioning features or use of this software | |
18 | .\" must display the following acknowledgement: | |
19 | .\" This product includes software developed by the NetBSD | |
20 | .\" Foundation, Inc. and its contributors. | |
21 | .\" 4. Neither the name of the The NetBSD Foundation nor the names of its | |
22 | .\" contributors may be used to endorse or promote products derived | |
23 | .\" from this software without specific prior written permission. | |
24 | .\" | |
25 | .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS | |
26 | .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED | |
27 | .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
28 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS | |
29 | .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
30 | .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
31 | .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
32 | .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
61f4f7c0 SW |
33 | .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
34 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
984263bc MD |
35 | .\" POSSIBILITY OF SUCH DAMAGE. |
36 | .\" | |
61f4f7c0 | 37 | .\" $FreeBSD: src/share/man/man4/gre.4,v 1.7 2006/10/19 07:41:47 danger Exp $ |
61f4f7c0 SW |
38 | .\" |
39 | .Dd November 11, 2007 | |
984263bc MD |
40 | .Dt GRE 4 |
41 | .Os | |
42 | .Sh NAME | |
43 | .Nm gre | |
44 | .Nd encapsulating network device | |
45 | .Sh SYNOPSIS | |
3906dd27 FF |
46 | To compile this driver into the kernel, place the following line |
47 | in the kernel configuration file: | |
61f4f7c0 SW |
48 | .Bd -ragged -offset indent |
49 | .Cd "pseudo-device gre" | |
50 | .Ed | |
51 | .Pp | |
3906dd27 FF |
52 | Alternatively, to load this driver as a module at boot time, |
53 | place the following line in | |
61f4f7c0 SW |
54 | .Xr loader.conf 5 : |
55 | .Bd -literal -offset indent | |
56 | if_gre_load="YES" | |
57 | .Ed | |
984263bc MD |
58 | .Sh DESCRIPTION |
59 | The | |
9b5a9965 | 60 | .Nm |
984263bc | 61 | network interface pseudo device encapsulates datagrams |
61f4f7c0 SW |
62 | into IP. |
63 | These encapsulated datagrams are routed to a destination host, | |
984263bc MD |
64 | where they are decapsulated and further routed to their final destination. |
65 | The | |
66 | .Dq tunnel | |
67 | appears to the inner datagrams as one hop. | |
68 | .Pp | |
69 | .Nm | |
70 | interfaces are dynamically created and destroyed with the | |
71 | .Xr ifconfig 8 | |
72 | .Cm create | |
73 | and | |
74 | .Cm destroy | |
75 | subcommands. | |
76 | .Pp | |
77 | This driver currently supports the following modes of operation: | |
61f4f7c0 SW |
78 | .Bl -tag -width indent |
79 | .It "GRE encapsulation (IP protocol number 47)" | |
984263bc | 80 | Encapsulated datagrams are |
61f4f7c0 SW |
81 | prepended an outer datagram and a GRE header. |
82 | The GRE header specifies | |
984263bc | 83 | the type of the encapsulated datagram and thus allows for tunneling other |
b911de4f | 84 | protocols than IP. |
61f4f7c0 SW |
85 | GRE mode is also the default tunnel mode on Cisco routers. |
86 | This is also the default mode of operation of the | |
87 | .Nm | |
984263bc | 88 | interfaces. |
61f4f7c0 SW |
89 | .\"As part of the GRE mode, |
90 | .\".Nm | |
91 | .\"also supports Cisco WCCP protocol, both version 1 and version 2. | |
92 | .\"Since there is no reliable way to distinguish between WCCP versions, it | |
93 | .\"should be configured manually using the | |
94 | .\".Cm link2 | |
95 | .\"flag. | |
96 | .\"If the | |
97 | .\".Cm link2 | |
98 | .\"flag is not set (default), then WCCP version 1 is selected. | |
99 | .It "MOBILE encapsulation (IP protocol number 55)" | |
984263bc | 100 | Datagrams are |
61f4f7c0 SW |
101 | encapsulated into IP, but with a shorter encapsulation. |
102 | The original | |
984263bc | 103 | IP header is modified and the modifications are inserted between the |
61f4f7c0 SW |
104 | so modified header and the original payload. |
105 | Like | |
984263bc | 106 | .Xr gif 4 , |
61f4f7c0 | 107 | only for IP-in-IP encapsulation. |
984263bc MD |
108 | .El |
109 | .Pp | |
110 | The | |
61f4f7c0 | 111 | .Nm |
984263bc MD |
112 | interfaces support a number of |
113 | .Xr ioctl 2 Ns s , | |
114 | such as: | |
61f4f7c0 SW |
115 | .Bl -tag -width ".Dv GRESADDRS" |
116 | .It Dv GRESADDRS | |
117 | Set the IP address of the local tunnel end. | |
118 | This is the source address | |
119 | set by or displayed by | |
120 | .Xr ifconfig 8 | |
121 | for the | |
122 | .Nm | |
984263bc | 123 | interface. |
61f4f7c0 SW |
124 | .It Dv GRESADDRD |
125 | Set the IP address of the remote tunnel end. | |
126 | This is the destination address | |
127 | set by or displayed by | |
128 | .Xr ifconfig 8 | |
129 | for the | |
130 | .Nm | |
984263bc | 131 | interface. |
61f4f7c0 SW |
132 | .It Dv GREGADDRS |
133 | Query the IP address that is set for the local tunnel end. | |
134 | This is the | |
135 | address the encapsulation header carries as local address (i.e., the real | |
136 | address of the tunnel start point). | |
137 | .It Dv GREGADDRD | |
138 | Query the IP address that is set for the remote tunnel end. | |
139 | This is the | |
140 | address the encapsulated packets are sent to (i.e., the real address of | |
141 | the remote tunnel endpoint). | |
142 | .It Dv GRESPROTO | |
143 | Set the operation mode to the specified IP protocol value. | |
144 | The | |
145 | protocol is passed to the interface in | |
146 | .Po Vt "struct ifreq" Pc Ns Li -> Ns Va ifr_flags . | |
984263bc | 147 | The operation mode can also be given as |
61f4f7c0 SW |
148 | .Pp |
149 | .Bl -tag -width ".Cm -link0" -compact | |
150 | .It Cm link0 | |
151 | .Dv IPPROTO_GRE | |
152 | .It Cm -link0 | |
153 | .Dv IPPROTO_MOBILE | |
984263bc MD |
154 | .El |
155 | .Pp | |
156 | to | |
157 | .Xr ifconfig 8 . | |
158 | .Pp | |
61f4f7c0 SW |
159 | The |
160 | .Cm link1 | |
161 | flag is not used to choose encapsulation, but to modify the | |
984263bc MD |
162 | internal route search for the remote tunnel endpoint, see the |
163 | .Sx BUGS | |
164 | section below. | |
61f4f7c0 | 165 | .It Dv GREGPROTO |
984263bc MD |
166 | Query operation mode. |
167 | .El | |
168 | .Pp | |
169 | Note that the IP addresses of the tunnel endpoints may be the same as the | |
170 | ones defined with | |
171 | .Xr ifconfig 8 | |
b911de4f | 172 | for the interface (as if IP is encapsulated), but need not be. |
984263bc MD |
173 | .Sh EXAMPLES |
174 | Configuration example: | |
175 | .Bd -literal | |
61f4f7c0 | 176 | Host X-- Host A ----------------tunnel---------- Cisco D------Host E |
984263bc MD |
177 | \\ | |
178 | \\ / | |
61f4f7c0 | 179 | +------Host B----------Host C----------+ |
984263bc | 180 | .Ed |
61f4f7c0 | 181 | .Pp |
984263bc | 182 | On host A |
61f4f7c0 SW |
183 | .Pq Dx : |
184 | .Bd -literal -offset indent | |
185 | route add default B | |
186 | ifconfig greN create | |
187 | ifconfig greN A D netmask 0xffffffff linkX up | |
188 | ifconfig greN tunnel A D | |
189 | route add E D | |
984263bc | 190 | .Ed |
61f4f7c0 | 191 | .Pp |
984263bc | 192 | On Host D (Cisco): |
61f4f7c0 SW |
193 | .Bd -literal -offset indent |
194 | Interface TunnelX | |
195 | ip unnumbered D ! e.g. address from Ethernet interface | |
196 | tunnel source D ! e.g. address from Ethernet interface | |
197 | tunnel destination A | |
198 | ip route C <some interface and mask> | |
199 | ip route A mask C | |
200 | ip route X mask tunnelX | |
984263bc | 201 | .Ed |
61f4f7c0 | 202 | .Pp |
984263bc | 203 | OR |
61f4f7c0 | 204 | .Pp |
984263bc | 205 | On Host D |
61f4f7c0 SW |
206 | .Pq Dx : |
207 | .Bd -literal -offset indent | |
208 | route add default C | |
209 | ifconfig greN create | |
210 | ifconfig greN D A | |
211 | ifconfig greN tunnel D A | |
984263bc MD |
212 | .Ed |
213 | .Pp | |
214 | If all goes well, you should see packets flowing ;-) | |
215 | .Pp | |
216 | If you want to reach Host A over the tunnel (from Host D (Cisco)), then | |
61f4f7c0 SW |
217 | you have to have an alias on Host A for e.g.\& the Ethernet interface like: |
218 | .Pp | |
219 | .Dl "ifconfig <etherif> alias Y" | |
220 | .Pp | |
221 | and on the Cisco: | |
222 | .Pp | |
223 | .Dl "ip route Y mask tunnelX" | |
984263bc MD |
224 | .Pp |
225 | A similar setup can be used to create a link between two private networks | |
226 | (for example in the 192.168 subnet) over the Internet: | |
227 | .Bd -literal | |
228 | 192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* | |
229 | \\ / | |
230 | \\ / | |
61f4f7c0 | 231 | +------ the Internet ------+ |
984263bc | 232 | .Ed |
61f4f7c0 | 233 | .Pp |
984263bc MD |
234 | Assuming router A has the (external) IP address A and the internal address |
235 | 192.168.1.1, while router B has external address B and internal address | |
236 | 192.168.2.1, the following commands will configure the tunnel: | |
237 | .Pp | |
238 | On router A: | |
61f4f7c0 SW |
239 | .Bd -literal -offset indent |
240 | ifconfig greN create | |
241 | ifconfig greN 192.168.1.1 192.168.2.1 link1 | |
242 | ifconfig greN tunnel A B | |
243 | route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 | |
984263bc MD |
244 | .Ed |
245 | .Pp | |
246 | On router B: | |
61f4f7c0 SW |
247 | .Bd -literal -offset indent |
248 | ifconfig greN create | |
249 | ifconfig greN 192.168.2.1 192.168.1.1 link1 | |
250 | ifconfig greN tunnel B A | |
251 | route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 | |
984263bc MD |
252 | .Ed |
253 | .Pp | |
61f4f7c0 SW |
254 | Note that this is a safe situation where the |
255 | .Cm link1 | |
256 | flag (as discussed in the | |
984263bc MD |
257 | .Sx BUGS |
258 | section below) may (and probably should) be set. | |
259 | .Sh NOTES | |
260 | The MTU of | |
61f4f7c0 SW |
261 | .Nm |
262 | interfaces is set to 1476 by default, to match the value used by Cisco routers. | |
984263bc | 263 | This may not be an optimal value, depending on the link between the two tunnel |
61f4f7c0 SW |
264 | endpoints. |
265 | It can be adjusted via | |
984263bc MD |
266 | .Xr ifconfig 8 . |
267 | .Pp | |
268 | For correct operation, the | |
269 | .Nm | |
270 | device needs a route to the destination that is less specific than the | |
271 | one over the tunnel. | |
272 | (Basically, there needs to be a route to the decapsulating host that | |
273 | does not run over the tunnel, as this would be a loop.) | |
274 | If the addresses are ambiguous, doing the | |
61f4f7c0 | 275 | .Nm ifconfig Cm tunnel |
984263bc MD |
276 | step before the |
277 | .Xr ifconfig 8 | |
278 | call to set the | |
61f4f7c0 | 279 | .Nm |
984263bc MD |
280 | IP addresses will help to find a route outside the tunnel. |
281 | .Pp | |
282 | In order to tell | |
283 | .Xr ifconfig 8 | |
61f4f7c0 SW |
284 | to actually mark the interface as |
285 | .Dq up , | |
286 | the keyword | |
287 | .Cm up | |
984263bc MD |
288 | must be given last on its command line. |
289 | .Pp | |
61f4f7c0 SW |
290 | The kernel must be set to forward datagrams by setting the |
291 | .Va net.inet.ip.forwarding | |
292 | .Xr sysctl 8 | |
293 | variable to non-zero. | |
984263bc | 294 | .Sh SEE ALSO |
984263bc MD |
295 | .Xr gif 4 , |
296 | .Xr inet 4 , | |
297 | .Xr ip 4 , | |
298 | .Xr netintro 4 , | |
984263bc MD |
299 | .Xr protocols 5 , |
300 | .Xr ifconfig 8 , | |
301 | .Xr sysctl 8 | |
302 | .Pp | |
303 | A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. | |
304 | .Pp | |
305 | A description of MOBILE encapsulation can be found in RFC 2004. | |
306 | .Sh AUTHORS | |
b2a6f486 | 307 | .An Heiko W. Rupp Aq Mt hwr@pilhuhn.de |
984263bc | 308 | .Sh BUGS |
61f4f7c0 | 309 | The |
a1a3b19e | 310 | .Fn gre_compute_route |
61f4f7c0 SW |
311 | code in |
312 | .Pa if_gre.c | |
313 | toggles the last bit of the | |
984263bc | 314 | IP-address to provoke the search for a less specific route than the |
61f4f7c0 SW |
315 | one directly over the tunnel to prevent loops. |
316 | This is possibly not the best solution. | |
984263bc | 317 | .Pp |
61f4f7c0 SW |
318 | To avoid the address munging described above, turn on the |
319 | .Cm link1 | |
320 | flag on the | |
984263bc MD |
321 | .Xr ifconfig 8 |
322 | command line. | |
323 | This implies that the GRE packet destination and the ifconfig remote host | |
324 | are not the same IP addresses, and that the GRE destination does not route | |
325 | over the | |
61f4f7c0 | 326 | .Nm |
984263bc MD |
327 | interface itself. |
328 | .Pp | |
329 | The GRE RFCs are not yet fully implemented (no GRE options). |