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

NAME
     gre -- encapsulating network device

SYNOPSIS
     device gre

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.

     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 tunnel greN 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.  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 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  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 GRE RFCs are not yet fully implemented (no GRE options).

FreeBSD 5.3			  June 9, 2002				  GRE(4)

home | help