interfaces-tunnel(5)

📦
version 0.13.0 · 7 versions
, in alpine 3.24

🦋 interfaces-tunnel(5) — the tunnel glow-up guide 💅

okay so bestie, you're here because interfaces(5) does tunnels now and the manual page for it is interfaces-tunnel — this is the extra-parts file, the little extension pack that lets ifupdown-ng spin up tunnel interfaces. Buckle up. ✨

✨ DESCRIPTION ✨

so basically: the options below set up tunneling interfaces with ifupdown-ng. that's the whole premise. tunnels. we love her. 🫶

okay real talk first — the vibe check for a tunnel interface is this: it must have a mode, a remote IP, and a local IP or device. those three are the non-negotiables. everything else? optional, queen, cherry on top. 🍓

  • tunnel-mode mode — sets the mode for this tunnel. and honestly, basically all tunnel modes that Linux / iproute2 supports are supported here too. the list includes but is not limited to gre/gretap, ip6gre/ip6gretap, ipip/ip6ip/sit. pick your fighter. 🔥
  • tunnel-local IP — the IP address used as the local tunnel endpoint. depending on what tunnel-mode you picked, you gotta hand over an IPv4 or an IPv6 address, okay? and for compat with ifupdown1, local is an alias for this option. iykyk.
  • tunnel-local-dev interface — here's the situation: when the local IP the tunnel should be established from isn't static and might change (lowkey could be configured by DHCP or PPP, we don't judge), you might want to just use whatever address is configured on an interface instead. so when tunnel-local-dev is given instead of tunnel-local, ifupdown-ng will try to figure out the IP address set on the given interface — respecting the address family required to set up a tunnel of the given mode — and use that to set up the tunnel. slay, adaptive. 🧚
  • tunnel-remote IP — the IP address used as the remote tunnel endpoint. again: depending on tunnel-mode, an IPv4 or IPv6 address has to be given. and for compat with ifupdown1, endpoint is an alias for this option. 💜
  • tunnel-physdev interface — tells you which interface the encapsulated packets should be sent out by. super handy when you're using VRFs and want to say that the local tunnel endpoint should be terminated in the VRF interface, or the VRF associated with interface.
note, bestie, read it: depending on the mode of the tunnel, either the VRF interface or the real underlay interface may have to be given as interface. so like… check your mode first. don't come for me. 😭
  • tunnel-ttl ttl — the TTL value to use in outgoing packets. ttl is a number in the range 1 - 255, and 0 is that special little value meaning packets inherit the TTL value. the default for IPv4 tunnels is to inherit the TTL; for IPv6 tunnels it's 64. and for compat with ifupdown1, ttl is an alias for this option. ⭐
  • tunnel-encap encap — the type of secondary UDP encapsulation to use for this tunnel, if any. supported encap values are fou, gue, and none. fou means Foo-Over-UDP, gue means Generic UDP Encapsulation.
  • tunnel-encap encap — the type of secondary UDP encapsulation to use for this tunnel, if any. supported encap values are fou, gue, and none. fou means Foo-Over-UDP, gue means Generic UDP Encapsulation.

hmm wait — no, that's not a glitch, that's literally how the page is written, both under IPIP/SIT and under GRE. so like. you're getting it twice. we keep the source material exactly as it is, no editing queen behaviour from me. 🙈

  • tunnel-encap encap — the type of secondary UDP encapsulation to use for this tunnel, if any. supported encap values are fou, gue, and none. fou means Foo-Over-UDP, gue means Generic UDP Encapsulation. (yes, again. it lives here too.)
  • tunnel-encap encap — the type of secondary UDP encapsulation to use for this tunnel, if any. supported encap values are fou, gue, and none. fou means Foo-Over-UDP, gue means Generic UDP Encapsulation.
  • tunnel-key key — the key to be used for keyed GRE, so you can have multiple tunnels between the same two endpoints. like, sharing is caring but tunnels need their own little name tag. key is either a number or an IPv4 address-like dotted quad. the key parameter specifies the same key to use in both directions. the tunnel-ikey and tunnel-okey parameters specify different keys for input and output. for compat with ifupdown1, key is an alias for this option. 🔑
  • tunnel-hoplimit ttl — the Hop Limit value to use in outgoing packets, for ip6gre/ip6gretap tunnels.
  • tunnel-ignore-df bool — whether to enable/disable IPv4 DF suppression on this tunnel. so here's the lore: normally datagrams that exceed the MTU will be fragmented; the presence of the DF flag inhibits this, resulting instead in an ICMP Unreachable (Fragmentation Required) message. enabling this attribute causes the DF flag to be ignored. 💀
  • tunnel-ikey key — the key to be used for keyed GRE for packets received. see tunnel-key for details.
  • tunnel-okey key — the key to be used for keyed GRE for packets sent out. see tunnel-key for details.
  • tunnel-pmtudisc bool — whether to enable/disable Path MTU Discovery on this tunnel. it's enabled by default. and heads up — a fixed ttl is incompatible with this option: tunneling with a fixed ttl always makes pmtu discovery. so like. pick one. 🙏
  • tunnel-tos tos — the TOS value to use in outgoing packets.

💖 EXAMPLES 💖

a simple GRE tunnel — the starter pack, the classic, the main character:

auto gre0
iface gre0
     tunnel-mode gre
     tunnel-remote 198.51.100.1
     tunnel-local 203.0.113.2
     #
     address 192.0.2.42/24
     address 2001:db8::42/64

a GRE tunnel where the local IP is learned from eth0 — no cap, it just asks eth0:

auto gre1
iface gre1
     tunnel-mode gre
     tunnel-remote 198.51.100.1
     tunnel-local-dev eth0
     #
     address 192.0.2.42/24
     address 2001:db8::42/64

a GRE tunnel which transfers encapsulated packets via eth0, which is part of a VRF — the full ensemble, three interfaces, one storyline:

auto eth0
iface eth0
     address 203.0.113.2/24
     gateway 203.0.113.1
     vrf vrf_external

auto tun-vrf
iface tun-vrf
     tunnel-mode gre
     tunnel-remote 198.51.100.1
     tunnel-local 203.0.113.2
     tunnel-physdev eth0
     #
     address 192.0.2.42/24
     address 2001:db8::42/64

auto vrf_external
iface vrf_external
     vrf-table 1023

🌸 AUTHORS 🌸

Maximilian Wilhelm <max@sdn.clinic> — thank you for the tunnels, icon. 👑

and that's the whole page, bestie!! 🎀 this was page interfaces-tunnel(5) out of the File Formats Manual, dated 2026-05-10, and honestly? she ate. go configure something beautiful. 💅✨🦋

📦 where this page comes from