gre(4)

NAME

gre - encapsulating network device

SYNOPSIS

device gre

DESCRIPTION

The gre network interface pseudo device encapsulates data

grams into IP.
These encapsulated datagrams are routed to a destination

host, where they
are decapsulated and further routed to their final destina

tion. 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 opera

tion:

GRE encapsulation (IP protocol number 47)

Encapsulated datagrams are prepended an outer data

gram and a GRE
header. The GRE header specifies the type of the

encapsulated
datagram and thus allows for tunneling other proto

cols than IP
like e.g. AppleTalk. GRE mode is also the default

tunnel mode on
Cisco routers. This is also the default mode of op

eration of the
gre interfaces. 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 (default), then WCCP version 1 is selected.

MOBILE encapsulation (IP protocol number 55)

Datagrams are encapsulated into IP, but with a

shorter encapsulation. 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 ifcon

fig(8) for the
gre interface.

GRESADDRD Set the IP address of the remote tunnel end.

This is the

destination address set by or displayed by

ifconfig(8) for
the gre interface.

GREGADDRS Query the IP address that is set for the lo

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

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

lation, but to
modify the internal route search for the re

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

pleTalk.

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 inter

face
tunnel source D ! e.g. address from Ethernet inter

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

justed 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. (Basi

cally, 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 am

biguous, 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), ifcon

fig(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 IPaddress 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 ad

dresses, and that
the GRE destination does not route over the gre interface

itself.

The GRE RFCs are not yet fully implemented (no GRE options).

BSD June 9, 2002

BSD