ip-tunnel
Create and manage network tunnels
SYNOPSIS
ip tunnel { add | change | delete | prl | show } [ dev NAME ] [ mode MODE ] [ remote ADDR ] [ OPTIONS ]
PARAMETERS
dev NAME
Tunnel device name (e.g., tun0)
mode MODE
Tunnel type: ipip, gre, sit, vti, ip6gre, ipip6, isatap, any
remote ADDR
Remote endpoint IP address
local ADDR
Local endpoint IP address
ttl|hoplimit TTL
Set TTL/hop limit (default copies inner)
tos TOS
Type of Service value
key KEY
GRE key for input/output (hex or int)
iseq|oseq
Enable input/output GRE sequence numbers
icsum|ocsum
Enable input/output GRE checksums
nopmtudisc
Disable PMTU discovery
ignore-df
Ignore DF bit for fragmentation
encap {lim|lookup} LIMIT|KEY
UDP encapsulation limit or lookup
uidrange UIDRANGE
UID range for VTI tunnels
nocache
Disable caching of dst entries
DESCRIPTION
The ip tunnel command, part of the iproute2 utilities, configures virtual tunnel devices for encapsulating network packets. It supports creating point-to-point or multipoint tunnels, essential for VPNs, IPv6 transition mechanisms, and private network overlays.
Tunnels wrap packets of one protocol inside another, such as IPv4 over IPv4 (ipip), IPv6 over IPv4 (sit), or multiprotocol with gre (Generic Routing Encapsulation). Other modes include vti for IPsec, ip6gre, ipip6, isatap, and any.
Use cases: site-to-site connectivity, remote access, or tunneling across incompatible networks. After creation, activate with ip link set dev tun0 up and configure routes via ip route.
Operations include add for new tunnels, change to modify, delete to remove, show to list, and prl for proxy route lists in multipoint setups. Options control endpoints (local, remote), headers (ttl, tos), security (key, csum), and encapsulation limits.
Requires root privileges and kernel support via modules like ip_gre.ko or tunnel4.ko. Integrates with netfilter for policy routing.
CAVEATS
Requires root access and loaded kernel modules (e.g., ip_gre, tunnel4). Not all modes support multipoint. PMTU issues common without proper config. IPv6 tunnels need IPv6 enabled.
COMMON EXAMPLE
Create GRE tunnel:
ip tunnel add gre1 mode gre remote 10.0.0.2 local 10.0.0.1 ttl 255
ip link set gre1 up
ip addr add 192.168.1.1/30 dev gre1
SUPPORTED MODES
ipip (IPv4-in-IPv4), sit (IPv6-in-IPv4), gre (multiprotocol), vti (IPsec), ip6gre (IPv6 GRE), ipip6 (IPv4-in-IPv6), isatap (Intra-Site Automatic Tunnel), any (autodetect)
HISTORY
Developed as part of iproute2 by Alexey Kuznetsov in late 1990s/early 2000s. Evolved with Linux kernel (2.4+), adding modes like VTI (2.6.36+) and FOUC encap. Maintained by netdev community.
