Create and Remove a GRE Tunnel with iptunnel

iptunnel is the older net-tools way to add, inspect and remove an IP tunnel. This guide walks through a GRE tunnel end to end: list, create, verify, remove.

The examples use iptunnel from net-tools 2.10-0.1ubuntu4.4, whose installed manual describes version 1.60 syntax. Allow about fifteen minutes, plus time to confirm the tunnel addresses and physical interface with whoever operates the remote host.

• Reading is safe. Checking the list and version is normally unprivileged.
• Writing is not. Adding, changing or deleting a tunnel needs elevated privileges and changes kernel networking state.
• A tunnel alone is not a connection. Both ends need compatible configuration plus any required addresses, routes and firewall rules.

1. Check the installed command

Establish which binary and package version you are using with these ordinary read-only checks:

$ command -v iptunnel
/usr/sbin/iptunnel
$ dpkg-query -W -f='${Package} ${Version}\n' net-tools
net-tools 2.10-0.1ubuntu4.4
$ iptunnel -V
net-tools 2.10
Alexey Kuznetsov

The version line is useful when comparing results with another machine. The command's -V output is from net-tools, while the local manual page is labelled version 1.60: keep both facts with an incident or change record instead of assuming a newer ip command has identical syntax.

$ iptunnel show

No output means this command found no configured IP tunnels, not that the host has no network interfaces. If a tunnel is listed, record its exact name before continuing: a later delete command must target that exact name.

2. Confirm the values for one GRE tunnel

The tunnel name is local to this host. The remote address is the destination of the outer IP packet, and the local address is its source. This example uses documentation-range addresses that must be replaced with real, reachable addresses on your network:

Replace every example address and eth0 with values that exist on this host. Do not use any for convenience unless accepting any source or destination is an intentional part of the design: the manual permits it, but a broad endpoint makes troubleshooting and filtering harder.

3. Add the GRE tunnel

Creation is a privileged, service-disrupting step for the host's networking namespace. Check the name and endpoints one more time, then run:

$ sudo iptunnel add gre-doc mode gre \
    remote 198.51.100.20 local 192.0.2.10 \
    ttl 64 dev eth0

A successful command produces no output. mode gre selects GRE, remote and local set the outer addresses, ttl 64 sets the tunnel time-to-live, and dev eth0 binds it to the physical device. The manual permits TTL values from 1 to 255 or inherit. A fixed TTL cannot be combined with nopmtudisc, so this example deliberately leaves path MTU discovery enabled.

$ iptunnel show gre-doc

The output format is build-specific. If the command reports that the name already exists, stop rather than overwriting an existing interface.

4. Add only the GRE features you need

GRE-specific options are available when the peer and design actually require them, and they are not interchangeable defaults:

• iseq requires incoming packet sequencing.
• oseq enables outgoing sequencing.
• ikey and okey set input and output GRE keys.
• icsum and ocsum require or calculate checksums.

A keyed tunnel must use the same agreed key on both ends. The manual accepts a numeric key or dotted-quad form:

$ sudo iptunnel add gre-doc-keyed mode gre \
    remote 198.51.100.20 local 192.0.2.10 \
    ikey 12345 okey 12345 dev eth0

Do not add sequencing, keys or checksums as trial-and-error flags: a mismatch can make an otherwise reachable peer fail, and the command does not negotiate these choices for you. If you create this second example, verify it with iptunnel show gre-doc-keyed and remove that exact name during cleanup.

5. Change a tunnel carefully

change uses the same option vocabulary as add and targets an existing name:

$ sudo iptunnel change gre-doc ttl 128
$ iptunnel show gre-doc

Changing tunnel parameters can interrupt traffic. Capture the old output before changing it and keep it as your rollback record. If the change is wrong, issue another privileged change with the previous values: do not assume that omitting an option clears it, specify the complete intended change and verify it afterwards.

6. Remove the test tunnel

$ sudo iptunnel del gre-doc
$ iptunnel show gre-doc
$ printf 'exit status: %s\n' "$?"
exit status: 1

The final status is expected because the named tunnel no longer exists; an empty result from iptunnel show is the check that actually matters. If you created gre-doc-keyed, remove it separately with sudo iptunnel del gre-doc-keyed.

7. Diagnose common failures

• Permission error. Means the operation needs the privileges available through your host's approved administration method. It does not prove the syntax is correct.
• Already exists error. Means the name is in use; inspect it before choosing another.
• Device error. Means the physical interface name is wrong, absent or not usable in the current network namespace.

If creation succeeds but the peer does not respond, separate local configuration from the path. Run iptunnel show NAME first, then check that the local address belongs to the host, the remote address is the peer's outer address, and firewalls permit GRE protocol traffic. remote and local describe the outer tunnel endpoints only; they do not configure an inner address or route.