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