diff options
Diffstat (limited to 'static/freebsd/man4/gre.4 3.html')
| -rw-r--r-- | static/freebsd/man4/gre.4 3.html | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/static/freebsd/man4/gre.4 3.html b/static/freebsd/man4/gre.4 3.html new file mode 100644 index 00000000..61256a86 --- /dev/null +++ b/static/freebsd/man4/gre.4 3.html @@ -0,0 +1,215 @@ +<table class="head"> + <tr> + <td class="head-ltitle">GRE(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">GRE(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">gre</code> — + <span class="Nd">encapsulating network device</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp">To compile the driver into the kernel, place the following line in + the kernel configuration file:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">device gre</code></div> +<p class="Pp">Alternatively, to load the driver as a module at boot time, place + the following line in <a class="Xr">loader.conf(5)</a>:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>if_gre_load="YES"</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">gre</code> 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 “tunnel” appears to the inner datagrams + as one hop.</p> +<p class="Pp"><code class="Nm">gre</code> interfaces are dynamically created and + destroyed with the <a class="Xr">ifconfig(8)</a> + <code class="Cm">create</code> and <code class="Cm">destroy</code> + subcommands.</p> +<p class="Pp">This driver corresponds to RFC 2784. 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. GRE mode is also the default tunnel mode on Cisco + routers. <code class="Nm">gre</code> also supports Cisco WCCP protocol, both + version 1 and version 2.</p> +<p class="Pp">The <code class="Nm">gre</code> interfaces support a number of + additional parameters to the <a class="Xr">ifconfig(8)</a>:</p> +<dl class="Bl-tag"> + <dt><var class="Ar">grekey</var></dt> + <dd>Set the GRE key used for outgoing packets. A value of 0 disables the key + option.</dd> + <dt><var class="Ar">enable_csum</var></dt> + <dd>Enables checksum calculation for outgoing packets.</dd> + <dt><var class="Ar">enable_seq</var></dt> + <dd>Enables use of sequence number field in the GRE header for outgoing + packets.</dd> + <dt><var class="Ar">udpencap</var></dt> + <dd>Enables UDP-in-GRE encapsulation (see the + <a class="Sx" href="#GRE_IN_UDP_ENCAPSULATION">GRE-IN-UDP + ENCAPSULATION</a> Section below for details).</dd> + <dt><var class="Ar">udpport</var></dt> + <dd>Set the source UDP port for outgoing packets. A value of 0 disables the + persistence of source UDP port for outgoing packets. See the + <a class="Sx" href="#GRE_IN_UDP_ENCAPSULATION">GRE-IN-UDP + ENCAPSULATION</a> Section below for details.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="GRE-IN-UDP_ENCAPSULATION"><a class="permalink" href="#GRE-IN-UDP_ENCAPSULATION">GRE-IN-UDP + ENCAPSULATION</a></h1> +<p class="Pp">The <code class="Nm">gre</code> supports GRE in UDP encapsulation + as defined in RFC 8086. A GRE in UDP tunnel offers the possibility of better + performance for load-balancing GRE traffic in transit networks. + Encapsulating GRE in UDP enables use of the UDP source port to provide + entropy to ECMP hashing.</p> +<p class="Pp">The GRE in UDP tunnel uses single value 4754 as UDP destination + port. The UDP source port contains a 14-bit entropy value that is generated + by the encapsulator to identify a flow for the encapsulated packet. The + <var class="Ar">udpport</var> option can be used to disable this behaviour + and use single source UDP port value. The value of + <var class="Ar">udpport</var> should be within the ephemeral port range, + i.e., 49152 to 65535 by default.</p> +<p class="Pp">Note that a GRE in UDP tunnel is unidirectional; the tunnel + traffic is not expected to be returned back to the UDP source port values + used to generate entropy. This may impact NAPT (Network Address Port + Translator) middleboxes. If such tunnels are expected to be used on a path + with a middlebox, the tunnel can be configured either to disable use of the + UDP source port for entropy or to enable middleboxes to pass packets with + UDP source port entropy.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<div class="Bd Li"> +<pre>192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* + \ / + \ / + +------ the Internet ------+</pre> +</div> +<p class="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:</p> +<p class="Pp">On router A:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>ifconfig greN create +ifconfig greN inet 192.168.1.1 192.168.2.1 +ifconfig greN inet tunnel A B +route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1</pre> +</div> +<p class="Pp">On router B:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>ifconfig greN create +ifconfig greN inet 192.168.2.1 192.168.1.1 +ifconfig greN inet tunnel B A +route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1</pre> +</div> +<p class="Pp">In case when internal and external IP addresses are the same, + different routing tables (FIB) should be used. The default FIB will be + applied to IP packets before GRE encapsulation. After encapsulation GRE + interface should set different FIB number to outgoing packet. Then different + FIB will be applied to such encapsulated packets. According to this FIB + packet should be routed to tunnel endpoint.</p> +<div class="Bd Pp Li"> +<pre>Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E + \ / + \ / + +----- Host B ----- Host C -----+ + (198.51.100.254)</pre> +</div> +<p class="Pp">On Host A (FreeBSD):</p> +<p class="Pp">First of multiple FIBs should be configured via loader.conf:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>net.fibs=2 +net.add_addr_allfibs=0</pre> +</div> +<p class="Pp">Then routes to the gateway and remote tunnel endpoint via this + gateway should be added to the second FIB:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0 +route add -host 203.0.113.1 -fib 1 198.51.100.254</pre> +</div> +<p class="Pp">And GRE tunnel should be configured to change FIB for encapsulated + packets:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>ifconfig greN create +ifconfig greN inet 198.51.100.1 203.0.113.1 +ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">The MTU of <code class="Nm">gre</code> 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 <a class="Xr">ifconfig(8)</a>.</p> +<p class="Pp">For correct operation, the <code class="Nm">gre</code> device + needs a route to the decapsulating host that does not run over the tunnel, + as this would be a loop.</p> +<p class="Pp">The kernel must be set to forward datagrams by setting the + <var class="Va">net.inet.ip.forwarding</var> <a class="Xr">sysctl(8)</a> + variable to non-zero.</p> +<p class="Pp">By default, <code class="Nm">gre</code> tunnels may not be nested. + This behavior may be modified at runtime by setting the + <a class="Xr">sysctl(8)</a> variable + <var class="Va">net.link.gre.max_nesting</var> to the desired level of + nesting.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">gif(4)</a>, <a class="Xr">inet(4)</a>, + <a class="Xr">ip(4)</a>, <a class="Xr">me(4)</a>, + <a class="Xr">netintro(4)</a>, <a class="Xr">protocols(5)</a>, + <a class="Xr">ifconfig(8)</a>, <a class="Xr">sysctl(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1> +<p class="Pp"><cite class="Rs"><span class="RsA">S. Hanks</span>, + <span class="RsA">T. Li</span>, <span class="RsA">D. Farinacci</span>, and + <span class="RsA">P. Traina</span>, <span class="RsT">Generic Routing + Encapsulation (GRE)</span>, <span class="RsR">RFC 1701</span>, + <span class="RsD">October 1994</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">S. Hanks</span>, + <span class="RsA">T. Li</span>, <span class="RsA">D. Farinacci</span>, and + <span class="RsA">P. Traina</span>, <span class="RsT">Generic Routing + Encapsulation over IPv4 networks</span>, <span class="RsR">RFC 1702</span>, + <span class="RsD">October 1994</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">D. Farinacci</span>, + <span class="RsA">T. Li</span>, <span class="RsA">S. Hanks</span>, + <span class="RsA">D. Meyer</span>, and <span class="RsA">P. Traina</span>, + <span class="RsT">Generic Routing Encapsulation (GRE)</span>, + <span class="RsR">RFC 2784</span>, <span class="RsD">March + 2000</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">G. Dommety</span>, + <span class="RsT">Key and Sequence Number Extensions to GRE</span>, + <span class="RsR">RFC 2890</span>, <span class="RsD">September + 2000</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Andrey V. Elsukov</span> + <<a class="Mt" href="mailto:ae@FreeBSD.org">ae@FreeBSD.org</a>> + <br/> + <span class="An">Heiko W.Rupp</span> + <<a class="Mt" href="mailto:hwr@pilhuhn.de">hwr@pilhuhn.de</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="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.</p> +<p class="Pp">The sequence number field also used only for outgoing packets.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 21, 2020</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |