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

NAME
     gre -- encapsulating network device

SYNOPSIS
     To compile the gre device into the kernel, place the following line in the
     kernel configuration file:

	   device gre

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

	   if_gre_load="YES"

DESCRIPTION
     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 currently supports the following modes of operation:

     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 gre in-
	     terfaces.	As part of the GRE mode, gre 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 link2 flag.  If the link2 flag is not  set  (de-
	     fault), then WCCP version 1 is selected.

     MOBILE encapsulation (IP protocol number 55)
	     Datagrams	are  encapsulated into IP, but with a shorter encapsula-
	     tion.  The original IP header is modified and the modifications are
	     inserted between the so modified header and the  original	payload.
	     Like gif(4), only for IP-in-IP encapsulation.

     The gre interfaces support a number of ioctl(2)s, such as:

     GRESADDRS	Set  the IP address of the local tunnel end.  This is the source
		address set by or displayed by ifconfig(8) for	the  gre  inter-
		face.

     GRESADDRD	Set the IP address of the remote tunnel end.  This is the desti-
		nation	address  set  by or displayed by ifconfig(8) for the gre
		interface.

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

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

     GRESPROTO	Set the operation mode to the specified IP protocol value.   The
		protocol    is	  passed    to	  the	interface   in	 (struct
		ifreq)->ifr_flags.  The operation mode can also be given as

		link0	IPPROTO_GRE
		-link0	IPPROTO_MOBILE

		to ifconfig(8).

		The link1 flag is not used to choose encapsulation, but to  mod-
		ify  the  internal  route search for the remote tunnel endpoint,
		see the "BUGS" section below.

     GREGPROTO	Query operation mode.

     GRESKEY	Set the GRE key used for outgoing packets.  A value  of  0  dis-
		ables the key option.

     GREGKEY	Get the GRE key currently used for outgoing packets.  0 means no
		outgoing key.

     Note  that  the IP addresses of the tunnel endpoints may be the same as the
     ones defined with ifconfig(8) for the interface (as if IP is encapsulated),
     but need not be, as e.g. when encapsulating AppleTalk.

EXAMPLES
     Configuration example:

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

     On host A (FreeBSD):

	   route add default B
	   ifconfig greN create
	   ifconfig greN A D netmask 0xffffffff linkX up
	   ifconfig greN tunnel A D
	   route add E D

     On Host D (Cisco):

	   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

     OR

     On Host D (FreeBSD):

	   route add default C
	   ifconfig greN create
	   ifconfig greN D A
	   ifconfig greN tunnel D A

     If all goes well, you should see packets flowing ;-)

     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:

	   ifconfig <etherif> alias Y

     and on the Cisco:

	   ip route Y mask tunnelX

     A similar setup can be used to create a link between two  private	networks
     (for example in the 192.168 subnet) over the Internet:

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

     On router B:

	   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

     Note  that  this  is a safe situation where the link1 flag (as discussed in
     the "BUGS" section below) may (and probably should) be set.

NOTES
     The MTU of gre 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 end-
     points.  It can be adjusted via ifconfig(8).

     For correct operation, the gre 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	ifconfig
     tunnel  step  before  the ifconfig(8) call to set the gre IP addresses will
     help to find a route outside the tunnel.

     In order to tell ifconfig(8) to actually mark the interface  as  "up",  the
     keyword up must be given last on its command line.

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

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

     A description of GRE encapsulation can be found in RFC 1701 and RFC 1702.

     A description of MOBILE encapsulation can be found in RFC 2004.

AUTHORS
     Heiko W.Rupp <hwr@pilhuhn.de>

BUGS
     The compute_route() code in 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.

     To avoid the address munging described above, turn on the link1 flag on the
     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 gre interface itself.

     The current implementation uses the key only for outgoing packets.   Incom-
     ming  packets  with  a different key or without a key will be treated as if
     they would belong to this interface.

     RFC1701 is not fully supported, however all unsupported features have  been
     deprecated in RFC2784.

FreeBSD 7.1			  June 20, 2008 			  GRE(4)

home | help