share/man/man4/gre.4

   1 .\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $
   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 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd June 2, 2015
  33 .Dt GRE 4
  34 .Os
  35 .Sh NAME
  36 .Nm gre
  37 .Nd encapsulating network device
  38 .Sh SYNOPSIS
  39 To compile the
  40 driver into the kernel, place the following line in the kernel
  41 configuration file:
  42 .Bd -ragged -offset indent
  43 .Cd "device gre"
  44 .Ed
  45 .Pp
  46 Alternatively, to load the
  47 driver as a module at boot time, place the following line in
  48 .Xr loader.conf 5 :
  49 .Bd -literal -offset indent
  50 if_gre_load="YES"
  51 .Ed
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 network interface pseudo device encapsulates datagrams
  56 into IP.
  57 These encapsulated datagrams are routed to a destination host,
  58 where they are decapsulated and further routed to their final destination.
  59 The
  60 .Dq tunnel
  61 appears to the inner datagrams as one hop.
  62 .Pp
  63 .Nm
  64 interfaces are dynamically created and destroyed with the
  65 .Xr ifconfig 8
  66 .Cm create
  67 and
  68 .Cm destroy
  69 subcommands.
  70 .Pp
  71 This driver corresponds to RFC 2784.
  72 Encapsulated datagrams are prepended an outer datagram and a GRE header.
  73 The GRE header specifies
  74 the type of the encapsulated datagram and thus allows for tunneling other
  75 protocols than IP like e.g.\& AppleTalk.
  76 GRE mode is also the default tunnel mode on Cisco routers.
  77 .Nm
  78 also supports Cisco WCCP protocol, both version 1 and version 2.
  79 .Pp
  80 The
  81 .Nm
  82 interfaces support a number of additional parameters to the
  83 .Xr ifconfig 8 :
  84 .Bl -tag -width "enable_csum"
  85 .It Ar grekey
  86 Set the GRE key used for outgoing packets.
  87 A value of 0 disables the key option.
  88 .It Ar enable_csum
  89 Enables checksum calculation for outgoing packets.
  90 .It Ar enable_seq
  91 Enables use of sequence number field in the GRE header for outgoing packets.
  92 .El
  93 .Sh EXAMPLES
  94 .Pp
  95 .Bd -literal
  96 192.168.1.* --- Router A  -------tunnel-------- Router B --- 192.168.2.*
  97                    \\                              /
  98                     \\                            /
  99                      +------ the Internet ------+
 100 .Ed
 101 .Pp
 102 Assuming router A has the (external) IP address A and the internal address
 103 192.168.1.1, while router B has external address B and internal address
 104 192.168.2.1, the following commands will configure the tunnel:
 105 .Pp
 106 On router A:
 107 .Bd -literal -offset indent
 108 ifconfig greN create
 109 ifconfig greN inet 192.168.1.1 192.168.2.1
 110 ifconfig greN inet tunnel A B
 111 route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
 112 .Ed
 113 .Pp
 114 On router B:
 115 .Bd -literal -offset indent
 116 ifconfig greN create
 117 ifconfig greN inet 192.168.2.1 192.168.1.1
 118 ifconfig greN inet tunnel B A
 119 route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
 120 .Ed
 121 .Pp
 122 In case when internal and external IP addresses are the same,
 123 different routing tables (FIB) should be used.
 124 The default FIB will be applied to IP packets before GRE encapsulation.
 125 After encapsulation GRE interface should set different FIB number to
 126 outgoing packet.
 127 Then different FIB will be applied to such encapsulated packets.
 128 According to this FIB packet should be routed to tunnel endpoint.
 129 .Bd -literal
 130 Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E
 131                    \\                                   /
 132                     \\                                 /
 133                      +----- Host B ----- Host C -----+
 134                        (198.51.100.254)
 135 .Ed
 136 .Pp
 137 On Host A (FreeBSD):
 138 .Pp
 139 First of multiple FIBs should be configured via loader.conf:
 140 .Bd -literal -offset indent
 141 net.fibs=2
 142 net.add_addr_allfibs=0
 143 .Ed
 144 .Pp
 145 Then routes to the gateway and remote tunnel endpoint via this gateway
 146 should be added to the second FIB:
 147 .Bd -literal -offset indent
 148 route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0
 149 route add -host 203.0.113.1 -fib 1 198.51.100.254
 150 .Ed
 151 .Pp
 152 And GRE tunnel should be configured to change FIB for encapsulated packets:
 153 .Bd -literal -offset indent
 154 ifconfig greN create
 155 ifconfig greN inet 198.51.100.1 203.0.113.1
 156 ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1
 157 .Ed
 158 .Pp
 159 .Sh NOTES
 160 The MTU of
 161 .Nm
 162 interfaces is set to 1476 by default, to match the value used by Cisco routers.
 163 This may not be an optimal value, depending on the link between the two tunnel
 164 endpoints.
 165 It can be adjusted via
 166 .Xr ifconfig 8 .
 167 .Pp
 168 For correct operation, the
 169 .Nm
 170 device needs a route to the decapsulating host that does not run over the tunnel,
 171 as this would be a loop.
 172 .Pp
 173 The kernel must be set to forward datagrams by setting the
 174 .Va net.inet.ip.forwarding
 175 .Xr sysctl 8
 176 variable to non-zero.
 177 .Sh SEE ALSO
 178 .\" Xr atalk 4 ,
 179 .Xr gif 4 ,
 180 .Xr inet 4 ,
 181 .Xr ip 4 ,
 182 .Xr me 4 ,
 183 .Xr netintro 4 ,
 184 .Xr protocols 5 ,
 185 .Xr ifconfig 8 ,
 186 .Xr sysctl 8
 187 .Pp
 188 A description of GRE encapsulation can be found in RFC 2784 and RFC 2890.
 189 .Sh AUTHORS
 190 .An Andrey V. Elsukov Aq Mt ae@FreeBSD.org
 191 .An Heiko W.Rupp Aq Mt hwr@pilhuhn.de
 192 .Sh BUGS
 193 .Pp
 194 The current implementation uses the key only for outgoing packets.
 195 Incoming packets with a different key or without a key will be treated as if they
 196 would belong to this interface.
 197 .Pp
 198 The sequence number field also used only for outgoing packets.