diff options
Diffstat (limited to 'share/man/man4/gre.4')
| -rw-r--r-- | share/man/man4/gre.4 | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/share/man/man4/gre.4 b/share/man/man4/gre.4 new file mode 100644 index 000000000000..827c93ec7202 --- /dev/null +++ b/share/man/man4/gre.4 @@ -0,0 +1,340 @@ +.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ +.\" +.\" 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. +.\" +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd June 20, 2008 +.Dt GRE 4 +.Os +.Sh NAME +.Nm gre +.Nd encapsulating network device +.Sh SYNOPSIS +To compile the +.Ns Nm +device into the kernel, place the following line in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device gre" +.Ed +.Pp +Alternatively, to load the +.Ns Nm +device as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_gre_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +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 indent +.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 +.Nm +interfaces. +As part of the GRE mode, +.Nm +also supports Cisco WCCP protocol, both version 1 and version 2. +Since there is no reliable way to distinguish between WCCP versions, it +should be configured manually using the +.Cm link2 +flag. +If the +.Cm link2 +flag is not set (default), then WCCP version 1 is selected. +.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 +.Nm +interfaces support a number of +.Xr ioctl 2 Ns s , +such as: +.Bl -tag -width ".Dv GRESADDRS" +.It Dv GRESADDRS +Set the IP address of the local tunnel end. +This is the source address +set by or displayed by +.Xr ifconfig 8 +for the +.Nm +interface. +.It Dv GRESADDRD +Set the IP address of the remote tunnel end. +This is the destination address +set by or displayed by +.Xr ifconfig 8 +for the +.Nm +interface. +.It Dv 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 Dv 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 Dv GRESPROTO +Set the operation mode to the specified IP protocol value. +The +protocol is passed to the interface in +.Po Vt "struct ifreq" Pc Ns Li -> Ns Va ifr_flags . +The operation mode can also be given as +.Pp +.Bl -tag -width ".Cm -link0" -compact +.It Cm link0 +.Dv IPPROTO_GRE +.It Cm -link0 +.Dv IPPROTO_MOBILE +.El +.Pp +to +.Xr ifconfig 8 . +.Pp +The +.Cm 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 Dv GREGPROTO +Query operation mode. +.It Dv GRESKEY +Set the GRE key used for outgoing packets. +A value of 0 disables the key option. +.It Dv GREGKEY +Get the GRE key currently used for outgoing packets. +0 means no outgoing key. +.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 +.Pp +On host A +.Pq Fx : +.Bd -literal -offset indent +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 +.Pp +On Host D (Cisco): +.Bd -literal -offset indent +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 <some interface and mask> +ip route A mask C +ip route X mask tunnelX +.Ed +.Pp +OR +.Pp +On Host D +.Pq Fx : +.Bd -literal -offset indent +route add default C +ifconfig greN create +ifconfig greN D A +ifconfig greN tunnel 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: +.Pp +.Dl "ifconfig <etherif> alias Y" +.Pp +and on the Cisco: +.Pp +.Dl "ip route Y mask tunnelX" +.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 +.Pp +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 -offset indent +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 -offset indent +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 +.Cm link1 +flag (as discussed in the +.Sx BUGS +section below) may (and probably should) be set. +.Sh NOTES +The MTU of +.Nm +interfaces is set to 1476 by default, to match the value used by Cisco routers. +If grekey is set this is lowered to 1472. +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 +.Nm ifconfig Cm tunnel +step before the +.Xr ifconfig 8 +call to set the +.Nm +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 +.Dq up , +the keyword +.Cm up +must be given last on its command line. +.Pp +The kernel must be set to forward datagrams by setting the +.Va net.inet.ip.forwarding +.Xr sysctl 8 +variable to non-zero. +.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 +.Fn compute_route +code in +.Pa 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 +.Cm 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 +.Nm +interface itself. +.Pp +The current implementation uses the key only for outgoing packets. +Incoming packets with a different key or without a key will be treated as if they +would belong to this interface. +.Pp +RFC1701 is not fully supported, however all unsupported features have been +deprecated in RFC2784. |