Provided by: ifupdown-ng_0.12.1-7_amd64 bug

NAME
       interfaces-tunnel - Tunnel extensions for the interfaces(5) 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 <max@sdn.clinic>

                                                   2025-03-25                               interfaces-tunnel(5)