Build and Remove a Point-to-Point IP Tunnel with ip tunnel

You will create an IP tunnel device between two Linux hosts, inspect the resulting configuration, and remove it without leaving a stale interface behind. The examples use a GRE tunnel, but the same workflow applies to IP-in-IP and the other modes supported by the installed iproute2 build.

Allow about 15 minutes for a basic configuration if you already know both endpoint addresses. This guide assumes two Linux hosts, root access through sudo, and an IPv4 address on each host that the other can reach. Replace every value marked with a placeholder before running a command.

What ip tunnel changes

An IP tunnel wraps packets in an outer IP packet and sends that packet through the ordinary IP network. The remote address is the far endpoint. The optional local address fixes the source address for the outer packet, and dev can pin the tunnel to a physical interface.

This command configures the tunnel device. It does not create routes for the networks you eventually want to carry through it, and it does not configure firewall rules. Those are separate changes. A tunnel device can exist while traffic still has nowhere useful to go.

The installed package here is iproute2 6.1.0-1ubuntu6.4, reporting iproute2-6.1.0. Its IPv4 tunnel modes include gre, ipip, sit, isatap and vti. IPv6 encapsulation uses a separate address-family selection and has different modes and defaults, so do not copy an IPv4 example into an IPv6 design without checking the matching documentation.

Step 1: record the endpoint details

Choose the outer addresses before touching the network configuration. In this example, host A uses 198.51.100.10, host B uses 198.51.100.20, and the tunnel device will be called gre-lab. The TEST-NET addresses are documentation values; use real addresses from your own network.

• Host A: 198.51.100.10
• Host B: 198.51.100.20
• Device name on both hosts: gre-lab

First check that the remote outer address is reachable from each host. This is an ordinary, non-privileged diagnostic command:

ping -c 3 198.51.100.20

Run the reverse check on host B. If the outer addresses cannot communicate, creating the tunnel will not fix that underlying problem. Check routing, firewalls and any provider policy before continuing.

Step 2: create the GRE device

Run this on host A. Creating a device changes live kernel networking state, so it requires elevated privileges. The mode gre argument selects GRE over IPv4. The remote and local values describe the outer endpoints, not the inner addresses you may later assign to the device.

sudo ip tunnel add gre-lab mode gre \
    remote 198.51.100.20 \
    local 198.51.100.10

Run the corresponding command on host B, swapping the endpoint addresses:

sudo ip tunnel add gre-lab mode gre \
    remote 198.51.100.10 \
    local 198.51.100.20

A successful ip tunnel add normally prints nothing. The most common immediate errors are an already-used device name, a missing tunnel mode, or an endpoint address that is not assigned to another interface on the local host. The manpage requires a fixed local address to belong to another local interface.

Checkpoint: inspect both devices

List the configured tunnels on each host:

ip tunnel show

Look for a line containing the device name, the GRE mode, and the expected remote and local addresses. The command has no arguments beyond the ip options and the tunnel show object. If it prints nothing, the add command did not leave a tunnel configured in that network namespace.

Step 3: choose the tunnel defaults deliberately

The basic command uses the defaults from the installed manpage. For an IPv4 tunnel, the outer packet TTL defaults to inherit, so the tunnelled packet's TTL is copied. Path MTU Discovery is enabled by default. The default is usually a sensible starting point: changing it can hide a real MTU problem or make diagnosis harder.

You can specify a fixed TTL when you have a reason to do so:

sudo ip tunnel change gre-lab ttl 64

This changes the existing device and still requires privilege. A fixed TTL is incompatible with nopmtudisc; the manpage says tunnelling with a fixed TTL always performs path MTU discovery. Do not add nopmtudisc merely because large packets fail. Investigate the path MTU first.

If you need different input and output GRE keys, use ikey and okey. A single key applies the same key in both directions. Keys are security-sensitive configuration, not encryption: a keyed GRE tunnel does not provide confidentiality. Avoid putting a real key in shell history or a shared transcript.

The dev option binds the tunnel to a physical device. This prevents the encapsulated packets escaping through another interface if the route to the remote endpoint changes:

sudo ip tunnel change gre-lab dev eth0

Only use eth0 after checking the actual interface name on that host. A wrong device can make the tunnel unusable. Inspect available interfaces with the non-changing command ip link show.

Step 4: add inner addressing only if you need it

ip tunnel add creates the tunnel object, but it does not assign an inner address or bring the device administratively up. If your design needs a point-to-point inner network, that is a separate interface operation and should use addresses and routes reserved for this purpose. Do not reuse the outer endpoint addresses.

For a lab-only inner network, an example would be:

sudo ip addr add 192.0.2.1/30 dev gre-lab
sudo ip link set gre-lab up

Use 192.0.2.1/30 on host A and the matching 192.0.2.2/30 on host B only in a controlled example, then test the inner address:

ping -c 3 192.0.2.2

Real networks should use an address range allocated for the tunnel. After assigning an address, verify it and the link state:

ip addr show dev gre-lab
ip link show dev gre-lab

If the inner ping fails, separate the layers. First confirm that ip tunnel show has the right outer endpoints. Then confirm the device is up, the inner addresses are correct, routes exist, and firewalls permit the protocol. GRE is not TCP or UDP, so a firewall rule that only permits familiar transport ports will not necessarily permit it.

Step 5: remove the test configuration

Removing a tunnel destroys the device and any inner addresses attached to it. This is a state-changing and potentially service-disrupting action. Stop traffic that depends on the tunnel and confirm the device name before running the command.

ip tunnel show
sudo ip tunnel del gre-lab

Run the delete command on both hosts. If you added an address or route separately, remove those separately according to the command that created them. For the example address, the matching cleanup command is:

sudo ip addr del 192.0.2.1/30 dev gre-lab

Remove the address before deleting the device when you need to clean up each operation explicitly. If the device has already been deleted, an address attached to it disappears with the device. Confirm the tunnel is gone:

ip tunnel show

The expected result is no line for gre-lab. If you get a "Cannot find device" or equivalent error during cleanup, inspect the current namespace with ip tunnel show and ip link show rather than repeating commands blindly.

Common traps

• Confusing outer and inner addresses: remote and local are for encapsulation. They do not replace an inner address or route.
• Assuming creation means connectivity: a configured device can still be down, unrouted, blocked by a firewall, or affected by an MTU limit.
• Using a duplicate name: tunnel names are device names in the current network namespace. Check with ip tunnel show before adding one.
• Changing defaults without a test: fixed TTL, disabled PMTU discovery, keys and checksums alter behaviour. Record the reason for each change so recovery is possible.
• Testing from the wrong namespace: network devices are namespace-local. Run inspection commands where the tunnel was created, especially when containers or network namespaces are involved.

Done means

• The two outer endpoint addresses can reach each other.
• ip tunnel show reports the intended mode, name and endpoints on both hosts.
• Any inner addresses and routes are separate, deliberate configuration.
• Firewall and MTU behaviour have been tested for the traffic you actually need.
• The tunnel has been deleted on both hosts when the test is finished, or its owner and rollback command are recorded.