Tunnel
Tunnel interfaces are virtual links that transmit encapsulated traffic between private networks or hosts across public infrastructure, such as the Internet. They operate using encapsulation protocols to wrap original traffic for transport. The supported protocols include GRE, IPIP, IPIP6, IP6IP6, and 6in4 (SIT).
While GRE is often the preferred one-size-fits-all solution due to its versatility, other encapsulation protocols may be better suited for specific use cases.
VyOS uses a single tunnel interface type for all of these protocols. There are
no separate GRE, IPIP, or IP6IP6
interface types; instead, the desired encapsulation protocol is selected within
the set interfaces tunnel configuration.
Configuration options for each protocol are described below.
Warning
Do not change the encapsulation type for already configured tunnel interfaces, as this may break their dependent configurations.
Common interface configuration
Configure one or more interface IP addresses.
<address> supports IPv4 and IPv6 in CIDR notation. For example, use
192.0.2.1/24 for IPv4 or 2001:db8::1/64 for IPv6.
Example:
set interfaces tunnel tun0 address 192.0.2.1/24
set interfaces tunnel tun0 address 2001:db8::1/64
Configure a clear, descriptive alias for the interface.
This alias appears in the show interfaces command and SNMP-based
monitoring tools.
Example:
set interfaces tunnel tun0 description 'This is an interface running on VyOS.'
Disable the interface.
The interface will be set to the administratively down
(A/D) state.
Example:
set interfaces tunnel tun0 disable
Disable Ethernet flow control (IEEE 802.3x pause frames) on the interface.
Ethernet flow control, defined by the IEEE 802.3x standard, temporarily stops data transmission to prevent packet loss during network congestion. For example, when a sender transmits data faster than the receiver can process it.
Disabling Ethernet flow control means the interface will not signal the connected device to pause transmission and will drop packets if overwhelmed.
Example:
set interfaces tunnel tun0 disable-flow-control
Disable physical link-state change detection on the interface, such as when a cable is unplugged.
By default, the interface detects physical link-state changes.
Example:
set interfaces tunnel tun0 disable-link-detect
Configure the MTU on the interface.
This value defines the largest packet size, in bytes, that the interface transmits without fragmentation.
Example:
set interfaces tunnel tun0 mtu 1600
Configure the MSS advertised in outgoing TCP SYN packets on the specified interface.
By clamping the MSS value in TCP SYN packets, you explicitly inform the remote side not to send packets larger than that size. This prevents connection issues that occur when Path MTU Discovery (PMTUD) fails.
The following options are available:
mss: Sets the MSS to a specific value, in bytes. Use this option if you need to enforce a specific MSS, for example, to troubleshoot connectivity issues or accommodate specific network requirements.
clamp-mss-to-pmtu: The router automatically calculates the MSS to be the interface’s MTU minus 40 bytes for IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). This option is recommended to automatically set the proper value.
Configure how long an ARP entry remains valid after learning an IP-to-MAC address mapping on this interface.
The default duration is 30 seconds.
An ARP entry remains valid if it receives positive feedback from higher-level protocols.
Example:
set interfaces tunnel tun0 ip arp-cache-timeout 180
Configure ARP filtering on this interface.
Default behavior: The kernel responds to ARP requests on this interface only if the traffic would be routed back to the ARP sender through that specific interface.
If configured: The kernel responds to ARP requests on this interface for any IP address configured on the local host, regardless of which specific interface that IP address is assigned to, and regardless of the routing table. This reflects the Linux concept that IP addresses belong to the host, not individual interfaces.
Example:
set interfaces tunnel tun0 ip disable-arp-filter
Configure the interface for host or router behavior.
If configured, the interface switches to host mode, and IPv4 forwarding is disabled on it.
Example:
set interfaces tunnel tun0 ip disable-forwarding
Configure whether to forward IP-directed broadcast packets received on this interface.
Default behavior: IP-directed broadcast packets are dropped.
If configured: IP-directed broadcast packets are forwarded to all hosts on the destination subnet, as defined in RFC 1812 and RFC 2644.
Example:
set interfaces tunnel tun0 ip enable-directed-broadcast
Configure how to process gratuitous ARPs on this interface.
If configured, an IP-to-MAC address mapping is added to the ARP table based on gratuitous ARP requests or replies.
Note
If the ARP table already contains the IP address from a gratuitous ARP, its entry is updated regardless of whether this setting is configured.
Example:
set interfaces tunnel tun0 ip enable-arp-accept
Configure the source IP selection for ARP requests on this interface.
Default behavior: The kernel can use any IP address the host owns as the source IP address in ARP requests on this interface.
If configured: The kernel first attempts to select a source IP address configured on the interface that shares a common subnet with the target IP address. If there is no such subnet, the kernel selects the IP address it would normally use (based on the routing table to reach the target destination).
Example:
set interfaces tunnel tun0 ip enable-arp-announce
Configure which ARP requests will be ignored on this interface.
Default behavior: The kernel responds to ARP requests for any local IP addresses, regardless of which interface they are assigned to.
If configured: The kernel responds to ARP requests only if the target IP address is assigned to this specific interface.
Example:
set interfaces tunnel tun0 ip enable-arp-ignore
Configure proxy ARP on this interface.
If configured, the router (kernel) intercepts ARP requests for non-local IP addresses and replies with the MAC address of the interface that received the request. Subsequent packets destined to these IP addresses are forwarded to their actual destinations on remote subnets.
Example:
set interfaces tunnel tun0 ip enable-proxy-arp
Configure local proxy ARP on the interface.
If configured, the router (kernel) responds to ARP requests on this VLAN interface even if the target IP address resides on the same subnet and interface.
This is used to support network isolation requirements (RFC 3069) for private VLANs (PVLANs). In PVLAN configurations, hosts on isolated ports are NOT allowed to communicate directly with each other at Layer 2, but they can communicate with the upstream router.
By replying to inter-host ARP requests with its own MAC address, the router (kernel) directs inter-host traffic through itself instead of directly between hosts.
Note
This command works independently and does not require enabling the standard proxy ARP on the interface.
Local proxy ARP is also known as:
VLAN aggregation (RFC 3069).
Private VLAN (Cisco, Allied Telesyn).
Source-port filtering or port isolation (Hewlett-Packard).
MAC-Forced Forwarding (Ericsson).
Configure source IP address validation using RPF on this interface, as specified in RFC 3704.
The following options are available:
strict: Each incoming packet’s source IP address is checked against the Forwarding Information Base (FIB). If the interface is not the best route back to that source, validation fails, and the packet is dropped.
loose: Each incoming packet’s source IP address is checked against the FIB. If the source IP address is unreachable through any interface, validation fails.
disable: No source IP address validation is performed. All incoming packets are accepted.
RFC 3704 recommends enabling strict mode to prevent IP spoofing, such as DDoS attacks. For asymmetric or other complex routing scenarios, use loose mode.
Configure the interface to automatically obtain an IPv6 address using SLAAC, as specified in RFC 4862.
IPv6 hosts can configure themselves automatically when connected to an IPv6 network using the Neighbor Discovery Protocol via ICMPv6 router discovery messages. When first connected to a network, a host sends a link-local router solicitation multicast request for its configuration parameters. The router responds with a router advertisement packet containing Internet Layer configuration parameters.
Note
This method automatically disables IPv6 traffic forwarding on the interface.
Example:
set interfaces tunnel tun0 ipv6 address autoconf
Configure the interface to assign itself an IPv6 address using the EUI-64 method, as specified in RFC 4291.
Example:
set interfaces tunnel tun0 ipv6 address eui64 2001:db8:beef::/64
Disable the automatic assignment of a link-local IPv6 address to this interface.
Example:
set interfaces tunnel tun0 ipv6 address no-default-link-local
Configure the interface for host or router behavior.
If configured, the interface switches to host mode, and IPv6 forwarding is disabled on it.
Example:
set interfaces tunnel tun0 ipv6 disable-forwarding
Configure the MSS advertised in outgoing TCP SYN packets on the specified interface.
By clamping the MSS value in TCP SYN packets, you explicitly inform the remote side not to send packets larger than that size. This prevents connection issues when Path MTU Discovery (PMTUD) fails.
The following options are available:
mss: Set the MSS to a specific value, in bytes. Use this option to enforce a specific MSS, for example, to troubleshoot connectivity issues or accommodate specific network requirements.
clamp-mss-to-pmtu: The router calculates the MSS to be the interface’s MTU minus 60 bytes for IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). This option is recommended to automatically set the proper value.
Configure IPv6 DAD on the interface.
The following options are available:
0: Disables DAD. No duplicate address detection is performed.
1: Enables DAD (default). Duplicate addresses are detected. The interface’s IPv6 operation continues for valid IPv6 addresses.
2: Enables DAD and, if a MAC-based duplicate link-local address is found, disables IPv6 operation on this interface.
Example:
set interfaces tunnel tun0 ipv6 accept-dad 2
Configure the number of DAD messages that the router (kernel) sends during IPv6 address assignment on this interface.
The default value is 1.
Example:
set interfaces tunnel tun0 ipv6 dup-addr-detect-transmits 5
Assign the interface to a specific VRF instance.
See also
For information on configuring a VRF, refer to the VRF section.
Example:
set interfaces tunnel tun0 vrf red
IPIP
IPIP is a straightforward encapsulation protocol defined in RFC 2003. It encapsulates one IPv4 packet inside another IPv4 packet.
Tunnels with IPIP encapsulation do not have protocol-specific configuration options except for explicitly defining the encapsulation type as IPIP (see the example below).
Example:
set interfaces tunnel tun0 encapsulation ipip
set interfaces tunnel tun0 source-address 192.0.2.10
set interfaces tunnel tun0 remote 203.0.113.20
set interfaces tunnel tun0 address 192.168.100.200/24
IP6IP6
IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside another IPv6 packet.
Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not have protocol-specific configuration options except for explicitly defining the encapsulation type as IP6IP6.
Example:
set interfaces tunnel tun0 encapsulation ip6ip6
set interfaces tunnel tun0 source-address 2001:db8:aa::1
set interfaces tunnel tun0 remote 2001:db8:aa::2
set interfaces tunnel tun0 address 2001:db8:bb::1/64
IPIP6
IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets.
Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6.
Example:
set interfaces tunnel tun0 encapsulation ipip6
set interfaces tunnel tun0 source-address 2001:db8:aa::1
set interfaces tunnel tun0 remote 2001:db8:aa::2
set interfaces tunnel tun0 address 192.168.70.80/24
6in4 (SIT)
6in4, also known as SIT, is an encapsulation protocol defined in RFC 4213 that wraps IPv6 packets inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, which is reserved exclusively for IPv6 encapsulation.
The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes over an underlying network with a standard MTU of 1500 bytes without fragmentation.
6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as Hurricane Electric) to connect isolated IPv6 networks or individual hosts to the IPv6 internet.
Example:
set interfaces tunnel tun0 encapsulation sit
set interfaces tunnel tun0 source-address 192.0.2.10
set interfaces tunnel tun0 remote 192.0.2.20
set interfaces tunnel tun0 address 2001:db8:bb::1/64
See also
For a practical configuration example, see the Tunnelbroker.net (IPv6) section.
Generic Routing Encapsulation (GRE)
GRE is a versatile encapsulation protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows both IPv4 and IPv6 to be transported through the same tunnel.
GRE encapsulates original data packets by adding a GRE header, followed by an IP header (the delivery header). The delivery header uses IP protocol number 47 to identify GRE-encapsulated traffic.
In VyOS, GRE tunnels can be established
over both IPv4 (encapsulation gre) and IPv6 (encapsulation ip6gre)
transport networks.
Configuration
To configure a GRE tunnel, you need to define a tunnel source IP address, a tunnel destination IP address, an encapsulation type (GRE), and a tunnel interface IP address.
Example:
The following example shows how to configure an IPv4/IPv6-over-IPv6 GRE tunnel between a VyOS router and a Linux host
running systemd-networkd.
VyOS router:
set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126'
set interfaces tunnel tun101 address '192.168.5.1/30'
set interfaces tunnel tun101 encapsulation 'ip6gre'
set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3'
set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5'
Linux systemd-networkd:
The systemd-networkd setup requires two configuration files: xxx.netdev
to create the GRE tunnel interface, and
xxx.network to assign IP addresses to it.
# cat /etc/systemd/network/gre-example.netdev
[NetDev]
Name=gre-example
Kind=ip6gre
MTUBytes=14180
[Tunnel]
Remote=2001:db8:babe:face::3afe:3
# cat /etc/systemd/network/gre-example.network
[Match]
Name=gre-example
[Network]
Address=2001:db8:feed:beef::2/126
[Address]
Address=192.168.5.2/30
GRE keys
A GRE key is an optional 32-bit field in the GRE header that allows multiple GRE tunnels to operate between the same source and destination endpoints. When a packet arrives, the receiver checks the GRE key to determine which tunnel interface should process it.
Although it may sound security-related, the GRE key is only an identifier and provides no encryption or data protection.
Example:
set interfaces tunnel tun0 source-address 192.0.2.10
set interfaces tunnel tun0 remote 192.0.2.20
set interfaces tunnel tun0 address 10.40.50.60/24
set interfaces tunnel tun0 parameters ip key 10
set interfaces tunnel tun1 source-address 192.0.2.10
set interfaces tunnel tun1 remote 192.0.2.20
set interfaces tunnel tun1 address 172.16.17.18/24
set interfaces tunnel tun1 parameters ip key 20
GRETAP
Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates Layer 2 (Ethernet) frames.
That means that GRETAP tunnel interfaces can be members of a bridge interface. This allows two geographically distant sites to connect as if they were on the same LAN.
GRETAP tunnels can be established over both IPv4 and IPv6 transport networks.
Example:
set interfaces bridge br0 member interface eth0
set interfaces bridge br0 member interface tun0
set interfaces tunnel tun0 encapsulation gretap
set interfaces tunnel tun0 source-address 198.51.100.2
set interfaces tunnel tun0 remote 203.0.113.10
Troubleshooting
GRE is a standardized tunneling protocol used in many network environments.
Although the GRE tunnel setup is straightforward, connectivity failures frequently occur because ACLs or firewall rules block IP protocol 47 or prevent direct communication between the tunnel endpoints.
If your GRE tunnel fails to establish, perform these diagnostic steps:
1. Verify that the remote peer is reachable from the configured
source-address.
This ensures that the underlying physical path between the two endpoints is functional.
vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4
PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data.
64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms
64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms
64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms
64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms
--- 203.0.113.10 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3007ms
rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms
2. Verify that the tunnel interface is correctly configured (with the link type set to GRE) and is actively processing traffic.
vyos@vyos:~$ show interfaces tunnel tun100
tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000
link/gre 198.51.100.2 peer 203.0.113.10
inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100
valid_lft forever preferred_lft forever
inet6 fe80::5efe:c612:2/64 scope link
valid_lft forever preferred_lft forever
RX: bytes packets errors dropped overrun mcast
2183 27 0 0 0 0
TX: bytes packets errors dropped carrier collisions
836 9 0 0 0 0
3. Test the connection through the tunnel using the private IP addresses assigned to each tunnel endpoint.
vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4
PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data.
64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms
64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms
--- 10.0.0.2 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3008ms
rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms