diff options
author | sobomax <sobomax@FreeBSD.org> | 2002-09-06 17:12:50 +0000 |
---|---|---|
committer | sobomax <sobomax@FreeBSD.org> | 2002-09-06 17:12:50 +0000 |
commit | 8379521a54a75b149798ce3088410a16e788cca6 (patch) | |
tree | 40ea63eb4828644495308e53b4e95f91d231de2a /share | |
parent | 49487ffa2c56cfdb3f1e348a058e462cc55e336d (diff) | |
download | FreeBSD-src-8379521a54a75b149798ce3088410a16e788cca6.zip FreeBSD-src-8379521a54a75b149798ce3088410a16e788cca6.tar.gz |
Add a new gre(4) driver, which could be used to create GRE (RFC1701)
and MOBILE (RFC2004) IP tunnels.
Obrained from: NetBSD
Diffstat (limited to 'share')
-rw-r--r-- | share/man/man4/gre.4 | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/share/man/man4/gre.4 b/share/man/man4/gre.4 new file mode 100644 index 0000000..825ea99 --- /dev/null +++ b/share/man/man4/gre.4 @@ -0,0 +1,279 @@ +.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright 1998 (c) The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Heiko W.Rupp <hwr@pilhuhn.de> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of the The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 9, 2002 +.Dt GRE 4 +.Os +.Sh NAME +.Nm gre +.Nd encapsulating network device +.Sh SYNOPSIS +.Cd pseudo-device gre +.Sh DESCRIPTION +The +.Nm gre +network interface pseudo device encapsulates datagrams +into IP. These encapsulated datagrams are routed to a destination host, +where they are decapsulated and further routed to their final destination. +The +.Dq tunnel +appears to the inner datagrams as one hop. +.Pp +.Nm +interfaces are dynamically created and destroyed with the +.Xr ifconfig 8 +.Cm create +and +.Cm destroy +subcommands. +.Pp +This driver currently supports the following modes of operation: +.Bl -tag -width abc +.It GRE encapsulation (IP protocol number 47) +Encapsulated datagrams are +prepended an outer datagram and a GRE header. The GRE header specifies +the type of the encapsulated datagram and thus allows for tunneling other +protocols than IP like e.g. AppleTalk. GRE mode is also the default tunnel +mode on Cisco routers. This is also the default mode of operation of the +.Sy gre Ns Ar X +interfaces. +.It MOBILE encapsulation (IP protocol number 55) +Datagrams are +encapsulated into IP, but with a shorter encapsulation. The original +IP header is modified and the modifications are inserted between the +so modified header and the original payload. Like +.Xr gif 4 , +only for IP in IP encapsulation. +.El +.Pp +The +.Sy gre Ns Ar X +interfaces support a number of +.Xr ioctl 2 Ns s , +such as: +.Bl -tag -width aaa +.It GRESADDRS : +Set the IP address of the local tunnel end. This is the source address +set by or displayed by ifconfig for the +.Sy gre Ns Ar X +interface. +.It GRESADDRD : +Set the IP address of the remote tunnel end. This is the destination address +set by or displayed by ifconfig for the +.Sy gre Ns Ar X +interface. +.It GREGADDRS : +Query the IP address that is set for the local tunnel end. This is the +address the encapsulation header carries as local address (i.e. the real +address of the tunnel start point.) +.It GREGADDRD : +Query the IP address that is set for the remote tunnel end. This is the +address the encapsulated packets are sent to (i.e. the real address of +the remote tunnel endpoint.) +.It GRESPROTO : +Set the operation mode to the specified IP protocol value. The +protocol is passed to the interface in (struct ifreq)-\*[Gt]ifr_flags. +The operation mode can also be given as +.Bl -tag -width link0xxx +.It link0 +IPPROTO_GRE +.It -link0 +IPPROTO_MOBILE +.El +.Pp +to +.Xr ifconfig 8 . +.Pp +The link1 flag is not used to choose encapsulation, but to modify the +internal route search for the remote tunnel endpoint, see the +.Sx BUGS +section below. +.It GREGPROTO : +Query operation mode. +.El +.Pp +Note that the IP addresses of the tunnel endpoints may be the same as the +ones defined with +.Xr ifconfig 8 +for the interface (as if IP is encapsulated), but need not be, as e.g. when +encapsulating AppleTalk. +.Sh EXAMPLES +Configuration example: +.Bd -literal +Host X-- Host A ----------------tunnel---------- cisco D------Host E + \\ | + \\ / + +------Host B----------Host C----------+ +.Ed +On host A +.Ns ( Nx ) : +.Bd -literal + # route add default B + # ifconfig greN create + # ifconfig greN A D netmask 0xffffffff linkX up + # ifconfig greN tunnel A D + # route add E D +.Ed +On Host D (Cisco): +.Bd -literal + Interface TunnelX + ip unnumbered D ! e.g. address from Ethernet interface + tunnel source D ! e.g. address from Ethernet interface + tunnel destination A + ip route C \*[Lt]some interface and mask\*[Gt] + ip route A mask C + ip route X mask tunnelX +.Ed +OR +On Host D +.Ns ( Nx ) : +.Bd -literal + # route add default C + # ifconfig greN create + # ifconfig greN D A + # ifconfig tunnel greN D A +.Ed +.Pp +If all goes well, you should see packets flowing ;-) +.Pp +If you want to reach Host A over the tunnel (from Host D (Cisco)), then +you have to have an alias on Host A for e.g. the Ethernet interface like: +.Bd -literal + ifconfig \*[Lt]etherif\*[Gt] alias Y +.Ed +and on the cisco +.Bd -literal + ip route Y mask tunnelX +.Ed +.Pp +A similar setup can be used to create a link between two private networks +(for example in the 192.168 subnet) over the Internet: +.Bd -literal +192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* + \\ / + \\ / + +----- the Internet ------+ +.Ed +Assuming router A has the (external) IP address A and the internal address +192.168.1.1, while router B has external address B and internal address +192.168.2.1, the following commands will configure the tunnel: +.Pp +On router A: +.Bd -literal + # ifconfig greN create + # ifconfig greN 192.168.1.1 192.168.2.1 link1 + # ifconfig greN tunnel A B + # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 +.Ed +.Pp +On router B: +.Bd -literal + # ifconfig greN create + # ifconfig greN 192.168.2.1 192.168.1.1 link1 + # ifconfig greN tunnel B A + # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 +.Ed +.Pp +Note that this is a safe situation where the link1 flag (as discussed in the +.Sx BUGS +section below) may (and probably should) be set. +.Sh NOTES +The MTU of +.Sy gre Ns Ar X +interfaces is set to 1476 by default to match the value used by Cisco routers. +This may not be an optimal value, depending on the link between the two tunnel +endpoints. It can be adjusted via +.Xr ifconfig 8 . +.Pp +For correct operation, the +.Nm +device needs a route to the destination that is less specific than the +one over the tunnel. +(Basically, there needs to be a route to the decapsulating host that +does not run over the tunnel, as this would be a loop.) +If the addresses are ambiguous, doing the +.Xr ifconfig 8 +.Li tunnel +step before the +.Xr ifconfig 8 +call to set the +.Sy gre Ns Ar X +IP addresses will help to find a route outside the tunnel. +.Pp +In order to tell +.Xr ifconfig 8 +to actually mark the interface as up, the keyword +.Dq up +must be given last on its command line. +.Pp +The kernel must be set to forward datagrams by either option +.Em GATEWAY +in the kernel config file or by issuing the appropriate option to +.Xr sysctl 8 . +.Sh SEE ALSO +.Xr atalk 4 , +.Xr gif 4 , +.Xr inet 4 , +.Xr ip 4 , +.Xr netintro 4 , +.Xr options 4 , +.Xr protocols 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Pp +A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. +.Pp +A description of MOBILE encapsulation can be found in RFC 2004. +.Sh AUTHORS +.An Heiko W.Rupp Aq hwr@pilhuhn.de +.Sh BUGS +The compute_route() code in if_gre.c toggles the last bit of the +IP-address to provoke the search for a less specific route than the +one directly over the tunnel to prevent loops. This is possibly not +the best solution. +.Pp +To avoid the address munging described above, turn on the link1 flag +on the +.Xr ifconfig 8 +command line. +This implies that the GRE packet destination and the ifconfig remote host +are not the same IP addresses, and that the GRE destination does not route +over the +.Sy gre Ns Ar X +interface itself. +.Pp +The GRE RFCs are not yet fully implemented (no GRE options). |