ip tunnel

ip tunnel add NAME mode gre local A remote B makes a card whose packets leave wrapped in a new IP header from A to B, with a 4-byte GRE header between (IP protocol 47). Give the card an address with ip addr, bring it up with ip link, and route networks into it with ip route: from then on it behaves like a cable between the two ends. The far end must be built as the mirror image. GRE adds 24 bytes, so the card's MTU is 1476, and it neither encrypts nor notices when the far end is gone.

ip tunnel command usage

ip tunnel add NAME mode gre|ipip|sit local ADDRESS remote ADDRESS [ttl N]
ip tunnel show [NAME]
ip tunnel change NAME remote ADDRESS
ip tunnel del NAME

Options

mode gre

wrap in GRE (protocol 47); ipip wraps IPv4 in IPv4 with no GRE header

local 10.0.11.2

this end's address: the outer packets' source

remote 10.0.12.2

the far end's address: the outer packets' destination

ttl 64

the outer header's TTL (otherwise copied from the inner packet)

ip tunnel examples

ip tunnel add toSiteB mode gre local 10.0.11.2 remote 10.0.12.2 ttl 64

Makes a GRE tunnel card from this router's public address to the other site's.

ip addr add 172.16.0.1/30 dev toSiteB; ip link set toSiteB up

Gives the tunnel an address of its own and brings it up.

ip tunnel show

Lists the tunnels with their mode and endpoints.

ip tunnel change toSiteA remote 10.0.11.2

Points an existing tunnel at a different far end.

Reading the output

$ ip tunnel show toSiteB; ip -d link show toSiteB
toSiteB: gre/ip remote 10.0.12.2 local 10.0.11.2 ttl 64
13: toSiteB@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/gre 10.0.11.2 peer 10.0.12.2 promiscuity 0 allmulti 0 minmtu 68 maxmtu 65511

• gre/ip: GRE carrying IPv4. remote and local are the outer header's addresses.
• mtu 1476: 1500 minus the 24 bytes of outer IP and GRE headers.
• state UNKNOWN with UP: normal for a tunnel. It has no carrier to lose, so it stays up whether or not the far end answers.

Pitfalls

• Every Linux host also shows gre0@NONE, tunl0@NONE and friends: placeholder cards the kernel makes when the tunnel modules load. They carry nothing.
• A firewall or NAT on the path must pass IP protocol 47 itself; GRE has no ports.
• Wrong remote on one end fails silently: both cards stay up, and the answers go nowhere.

Run it on real machines