TC-TUNNEL_KEY(8)

✨ tc-tunnel_key(8) ✨

Tunnel metadata action in tc(8) 💖 Linux

💫 NAME 💫

tunnel_key — okay so this is your tunnel metadata manipulation action 🫶

🎀 SYNOPSIS 🎀

tc ... action tunnel_key { unset | SET }

SET := set src_ip ADDRESS dst_ip ADDRESS id KEY_ID dst_port UDP_PORT tos
        TOS ttl TTL [ csum | nocsum ]

🦋 DESCRIPTION 🦋

Okay bestie, so the tunnel_key action is giving tunnel vibes when it teams up with a shared IP tunnel device 🌸 It lets you do IP tunnel en- or decapsulation on a packet, and the two modes are UNSET and SET ✨

UNSET is optional. Even if you skip it, the metadata gets released automatically once packet processing is done, so no stress 💅 It comes in handy when traffic is being forwarded between two tunnels, and the metadata from the first tunnel is used for the encapsulation done by the second one. Main character energy 👑

SET is the one that needs the source and destination IP ADDRESS plus the tunnel key id KEY_ID. The shared IP tunnel device uses those to build the tunnel header 🧚 Honestly the tunnel_key action is only really useful alongside a mirred redirect action to a shared IP tunnel device. That device is the one that uses the metadata (for SET) and unsets the metadata it created (for UNSET) 🔥

🌈 OPTIONS 🌈

• unset — unsets the tunnel metadata that the IP tunnel device created 🫧 This isn't mandatory and only shows up in some specific use cases, as we covered above.
• set — sets the tunnel metadata for the IP tunnel device to use 💜 You need src_ip and dst_ip for this one. id, dst_port, geneve_opts, vxlan_opts and erspan_opts are optional bonuses ✨
  • id — the tunnel ID (like the VNI in a VXLAN tunnel) 🍓
  • src_ip — the outer header source IP address (IPv4 or IPv6) 🌷
  • dst_ip — the outer header destination IP address (IPv4 or IPv6) 🌷
  • dst_port — the outer header destination UDP port 🦋
  • geneve_opts — Geneve variable length options 🔮 The format is CLASS:TYPE:DATA. CLASS is a 16bit hexadecimal value, TYPE is an 8bit hexadecimal value, and DATA is a variable length hexadecimal value. You can list several options at once by separating them with a comma 🎀
  • vxlan_opts — VXLAN metadata options 🌸 The format is just GBP, a 32bit number. Heads up, multiple options aren't supported here 🙈
  • erspan_opts — ERSPAN metadata options 🧚 The format is VERSION:INDEX:DIR:HWID. VERSION is an 8bit number, INDEX is a 32bit number, and DIR and HWID are each an 8bit number. Multiple options aren't supported 💀 Also, INDEX is used when VERSION is 1, and DIR and HWID are used when VERSION is 2 🫶
  • tos — outer header TOS 💅
  • ttl — outer header TTL 💅
  • [no]csum — controls the outer UDP checksum 🔥 With csum (the default), the outer UDP checksum gets calculated and included in the packets. With nocsum, the outer UDP checksum is zero. Note that if you use zero UDP checksums with IPv6, the other tunnel endpoint has to be configured to accept those packets. On Linux, that's the udp6zerocsumrx option for the VXLAN tunnel interface 🌈

🙈 If you use nocsum with IPv6, make sure you actually know what you're doing. Zero UDP checksums give you weaker protection against corrupted packets. See RFC6935 for details.

• nofrag — disallows IP fragmentation 🚫

💌 EXAMPLES 💌

Okay this first one is so cute 🎀 It encapsulates incoming ICMP packets on eth0 into a vxlan tunnel. It sets the metadata to VNI 11, source IP 11.11.0.1 and destination IP 11.11.0.2, then redirects the packet with that metadata to the device vxlan0, which does the actual encapsulation using the metadata:

#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev eth0 protocol ip parent ffff: \
  flower \
    ip_proto icmp \
  action tunnel_key set \
    src_ip 11.11.0.1 \
    dst_ip 11.11.0.2 \
    id 11 \
  action mirred egress redirect dev vxlan0

And here's the unset function in action 🦋 Incoming VXLAN traffic with outer IPs and VNI 11 gets decapsulated by vxlan0, and the metadata is unset before it's redirected to the tunl1 device:

#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev vxlan0 protocol ip parent ffff:   flower \
       enc_src_ip 11.11.0.2 enc_dst_ip 11.11.0.1 enc_key_id 11   action tunnel_key unset  action mirred egress redirect dev tunl1

📚 SEE ALSO 📚

• tc(8) 🧚

iproute2 · 10 Nov 201… 💖 Stay iconic, bestie, and see you in the next packet 🫶✨