GRE(4)

gre(4) 🦋 — encapsulating network device

okay bestie, sit down, hydrate, because we're talking about gre — the FreeBSD kernel's encapsulating network device, and honestly? it's giving tunnel main character energy 💅

---

🌸 NAME 🌸

gre — encapsulating network device ✨

---

🎀 SYNOPSIS 🎀

so like, if you wanna bake this driver right into the kernel, you drop this line into your kernel config file:

device gre

OR, if you'd rather load it as a module at boot time (iconic, flexible, no recompile), you put this in loader.conf(5):

if_gre_load="YES"

---

✨ DESCRIPTION ✨

The gre network interface pseudo device encapsulates datagrams into IP. Those cute little wrapped-up datagrams get routed to a destination host, where they get decapsulated and then routed onward to their final destination. From the inner datagrams' point of view, the “tunnel” looks like just one hop. one hop! the way it just skips the whole internet 😭

gre interfaces are dynamically created and destroyed with the ifconfig(8) create and destroy subcommands. no cap.

This driver corresponds to RFC 2784. Encapsulated datagrams get an outer datagram and a GRE header prepended. The GRE header specifies the type of the encapsulated datagram, which is how it's able to tunnel other protocols besides IP. GRE mode is also the default tunnel mode on Cisco routers (iykyk 🫶). gre also supports the Cisco WCCP protocol — both version 1 and version 2.

The gre interfaces support a whole lil lineup of extra parameters for ifconfig(8):

• grekey — sets the GRE key used for outgoing packets. A value of 0 disables the key option. 💅
• enable_csum — enables checksum calculation for outgoing packets. ✨
• enable_seq — enables use of the sequence number field in the GRE header for outgoing packets. 🔢
• udpencap — enables UDP-in-GRE encapsulation (peep the “GRE-IN-UDP ENCAPSULATION” section down below for the deets). 🫧
• udpport — sets the source UDP port for outgoing packets. A value of 0 disables the persistence of source UDP port for outgoing packets. Again, see the “GRE-IN-UDP ENCAPSULATION” section for the details. 🌈

---

🦋 GRE-IN-UDP ENCAPSULATION 🦋

The gre 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. slay.

The GRE in UDP tunnel uses the single value 4754 as the 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 udpport option can be used to disable this behaviour and use a single source UDP port value instead. The value of udpport should be within the ephemeral port range, i.e., 49152 to 65535 by default.

ngl bestie, 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. choose your fighter 💀

---

🌈 EXAMPLES 🌈

192.168.1.* --- Router A  -------tunnel-------- Router B --- 192.168.2.*
                     \                              /
                      \                            /
                       +------ the Internet ------+

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. 🛠️

On router A:

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

On router B:

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

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, the GRE interface should set a different FIB number to the outgoing packet. Then a different FIB will be applied to such encapsulated packets. According to this FIB, the packet should be routed to the tunnel endpoint. ✨

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)

On Host A (FreeBSD):

First of multiple FIBs should be configured via loader.conf:

net.fibs=2
net.add_addr_allfibs=0

Then routes to the gateway and remote tunnel endpoint via this gateway should be added to the second FIB:

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

And the GRE tunnel should be configured to change FIB for encapsulated packets:

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

---

💜 NOTES 💜

The MTU of gre 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 ifconfig(8).

For correct operation, the gre device needs a route to the decapsulating host that does not run over the tunnel, as this would be a loop. 🔁 (not the cute kind of loop, bestie.)

The kernel must be set to forward datagrams by setting the net.inet.ip.forwarding sysctl(8) variable to non-zero.

By default, gre tunnels may not be nested. This behavior may be modified at runtime by setting the sysctl(8) variable net.link.gre.max_nesting to the desired level of nesting. go off 🎀

---

👑 SEE ALSO 👑

gif(4), inet(4), ip(4), me(4), netintro(4), protocols(5), ifconfig(8), sysctl(8)

---

⭐ STANDARDS ⭐

• S. Hanks, T. Li, D. Farinacci, and P. Traina, Generic Routing Encapsulation (GRE), RFC 1701, October 1994.
• S. Hanks, T. Li, D. Farinacci, and P. Traina, Generic Routing Encapsulation over IPv4 networks, RFC 1702, October 1994.
• D. Farinacci, T. Li, S. Hanks, D. Meyer, and P. Traina, Generic Routing Encapsulation (GRE), RFC 2784, March 2000.
• G. Dommety, Key and Sequence Number Extensions to GRE, RFC 2890, September 2000.

---

🫶 AUTHORS 🫶

• Andrey V. Elsukov <ae@FreeBSD.org>
• Heiko W.Rupp <hwr@pilhuhn.de>

give them their flowers fr fr 💐

---

💀 BUGS 💀

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. 🙈

The sequence number field also used only for outgoing packets.

so yeah, one-way street energy. outgoing only, both of them. just so you know what you're getting into 💅

---

and that's the whole page bestie, we ate and left no crumbs ✨ this gem comes from the Debian distribution, dated August 21, 2020, and it lives in the manual as GRE(4) 🦋💖 good luck tunneling, you've got this 🫶