Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GRE(4)		       FreeBSD Kernel Interfaces Manual			GRE(4)

     gre -- encapsulating network device

     To	compile	the driver into	the kernel, place the following	line in	the
     kernel configuration file:

	   device gre

     Alternatively, to load the	driver as a module at boot time, place the
     following line in loader.conf(5):


     The 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
     "tunnel" appears to the inner datagrams as	one hop.

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

     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.  gre also	supports Cisco WCCP protocol, both version 1 and ver-
     sion 2.

     The gre interfaces	support	a number of additional parameters to the

     grekey	  Set 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 sequence number field in the GRE header for
		  outgoing packets.

     udpencap	  Enables UDP-in-GRE encapsulation (see	the GRE-IN-UDP
		  ENCAPSULATION	Section	below for details).

     udpport	  Set the source UDP port for outgoing packets.	 A value of 0
		  disables the persistence of source UDP port for outgoing
		  packets.  See	the GRE-IN-UDP ENCAPSULATION Section below for

     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-bal-
     ancing GRE	traffic	in transit networks.  Encapsulating GRE	in UDP enables
     use of the	UDP source port	to provide entropy to ECMP hashing.

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

     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.

     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	ad-
     dress,	while router B has external address B and internal ad-
     dress,	the following commands will configure the tunnel:

     On	router A:

	   ifconfig greN create
	   ifconfig greN inet
	   ifconfig greN inet tunnel A B
	   route add -net 192.168.2 -netmask

     On	router B:

	   ifconfig greN create
	   ifconfig greN inet
	   ifconfig greN inet tunnel B A
	   route add -net 192.168.1 -netmask

     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.

     Host X -- Host A ( ---tunnel--- Cisco	D (	-- Host	E
			\				    /
			 \				   /
			  +----- Host B	----- Host C -----+

     On	Host A (FreeBSD):

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


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

	   route add -net -netmask -fib 1 -iface em0
	   route add -host -fib 1

     And GRE tunnel should be configured to change FIB for encapsulated	pack-

	   ifconfig greN create
	   ifconfig greN inet
	   ifconfig greN inet tunnel tunnelfib	1

     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

     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.

     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 to
     the desired level of nesting.

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

     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.

     Andrey V. Elsukov <>
     Heiko W.Rupp <>

     The current implementation	uses the key only for outgoing packets.	 In-
     coming 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.

FreeBSD	13.0			August 21, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help