--- name: "interfaces-tunnel" section: "5" platform: "linux" package: "ifupdown-ng" version: "0.12.1-7" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/interfaces-tunnel" --- # interfaces-tunnel(5) Tunnel extensions for the interfaces(5) file format ## NAME **interfaces-tunnel** - Tunnel extensions for the [interfaces(5)](/interfaces/5.md) file format ## DESCRIPTION The following options set up tunneling interfaces with ifupdown-ng. ## TUNNEL-RELATED OPTIONS A tunnel interface must have a mode, remote IP and a local IP or device set, all other options are optional. **tunnel-mode** *mode* Denotes the mode for this tunnel. Basically all tunnel modes supported by Linux / iproute2 are supported as well. This includes but is not limited to *gre*/*gretap*, *ip6gre*/*ip6gretap*, *ipip*/*ip6ip*/*sit*. **tunnel-local** *IP* Denotes the IP address used as the local tunnel endpoint. According to the *tunnel-mode* an IPv4 or IPv6 address has to be given. For compatiblity to ifupdown1 *local* is an alias for this option. **tunnel-local-dev** *interface* When the local IP address the tunnel should be established from isn't static and therefore might change (e.g. configured by DHCP or PPP) it might be desireable to just use the address configured on *interface*. When *tunnel-local-dev* is given instead of *tunnel-local* ifupdown-ng will try to determine the IP address set on the given *interface* with respect to the address family required to set up a tunnel of the given *mode* and use this to set up the tunnel. **tunnel-remote** *IP* Denotes the IP address used as the remote tunnel endpoint. According to the *tunnel-mode* an IPv4 or IPv6 address has to be given. For compatiblity to ifupdown1 *endpoint* is an alias for this option. **tunnel-physdev** *interface* Denotes the *interface* the encapsulated packets should be sent out by. This comes in handy when using VRFs to denote that the local tunnel endpoint should be terminated in VRF *interface* or the VRF associated with *interface*. Note: Depending on the *mode* of the tunnel either the VRF interface or the real underlay interface may have to given as *interface*. **tunnel-ttl** *ttl* Denotes the TTL value to use in outgoing packets. *ttl* is a number in the range 1 - 255 whereas 0 is a special value meaning that packets inherit the TTL value. The default for IPv4 tunnels is to inherit the TTL, for IPv6 tunnels it's 64. For compatiblity to ifupdown1 *ttl* is an alias for this option. ## IPIP/SIT-RELATED OPTIONS **tunnel-encap** *encap* Denotes the type of secondary UDP encapsulation to use for this tunnel if any. Supported *encap* values are *fou*, *gue*, and *none*. *fou* indicates Foo-Over-UDP, *gue* indicates Generic UDP Encapsulation. ## GRE-RELATED OPTIONS **tunnel-encap** *encap* Denotes the type of secondary UDP encapsulation to use for this tunnel if any. Supported *encap* values are *fou*, *gue*, and *none*. *fou* indicates Foo-Over-UDP, *gue* indicates Generic UDP Encapsulation. **tunnel-key** *key* Denotes the\_key to used for keyed GRE to allow multiple tunnels between the same two endpoints. *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 compatiblity to ifupdown1 *key* is an alias for this option. **tunnel-hoplimit** *ttl* Denotes the Hop Limit value to use in outgoing packets for *ip6gre*/*ip6gretap* tunnels. **tunnel-ignore-df** *bool* Denotes wether to enable/disable IPv4 DF suppression on this tunnel. 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* Denotes the key to used for keyed GRE for packets received. See *tunnel-key* for details. **tunnel-okey** *key* Denotes the key to used for keyed GRE for packets sent out. See *tunnel-key* for details. **tunnel-pmtudisc** *bool* Denotes wether to enable/disable Path MTU Discovery on this tunnel. It is enabled by default. Note that a fixed ttl is incompatible with this option: tunneling with a fixed ttl always makes pmtu discovery. **tunnel-tos** *tos* Denotes the TOS value to use in outgoing packets. ## EXAMPLES A simple GRE tunnel ``` 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* ``` 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 encapasulated packets via *eth0* which is part of a VRF. ``` 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 \