VTI (virtual tunnel interface)

VTIs let you create secure, encrypted tunnels between private networks or hosts across public infrastructure, such as the Internet. They operate alongside an underlying IPsec tunnel, which handles encapsulation and encryption, while VTIs function exclusively as routing interfaces.

Configuration

Common interface configuration

set interfaces vti <interface> address <address>

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 vti vti0 address 192.0.2.1/24
set interfaces vti vti0 address 2001:db8::1/64
set interfaces vti <interface> description <description>

Configure a clear, descriptive alias for the interface.

This alias appears in the show interfaces command and SNMP-based monitoring tools.

Example:

set interfaces vti vti0 description 'This is an interface running on VyOS.'
set interfaces vti <interface> disable

Disable the interface.

The interface will be set to the administratively down (A/D) state.

Example:

set interfaces vti vti0 disable
set interfaces vti <interface> ip adjust-mss <mss | clamp-mss-to-pmtu>

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.

set interfaces vti <interface> ip arp-cache-timeout

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 vti vti0 ip arp-cache-timeout 180
set interfaces vti <interface> ip disable-arp-filter

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 vti vti0 ip disable-arp-filter
set interfaces vti <interface> ip disable-forwarding

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 vti vti0 ip disable-forwarding
set interfaces vti <interface> ip enable-directed-broadcast

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 vti vti0 ip enable-directed-broadcast
set interfaces vti <interface> ip enable-arp-accept

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 vti vti0 ip enable-arp-accept
set interfaces vti <interface> ip enable-arp-announce

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 vti vti0 ip enable-arp-announce
set interfaces vti <interface> ip enable-arp-ignore

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 vti vti0 ip enable-arp-ignore
set interfaces vti <interface> ip enable-proxy-arp

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 vti vti0 ip enable-proxy-arp
set interfaces vti <interface> ip proxy-arp-pvlan

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).

set interfaces vti <interface> ip source-validation <strict | loose | disable>

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.

set interfaces vti <interface> ipv6 address autoconf

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 vti vti0 ipv6 address autoconf
set interfaces vti <interface> ipv6 address eui64 <prefix>

Configure the interface to assign itself an IPv6 address using the EUI-64 method, as specified in RFC 4291.

Example:

set interfaces vti vti0 ipv6 address eui64 2001:db8:beef::/64
set interfaces vti <interface> ipv6 address no-default-link-local

Disable the automatic assignment of a link-local IPv6 address to this interface.

Example:

set interfaces vti vti0 ipv6 address no-default-link-local
set interfaces vti <interface> ipv6 disable-forwarding

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 vti vti0 ipv6 disable-forwarding
set interfaces vti <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu>

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.

set interfaces vti <interface> ipv6 accept-dad <0 | 1 | 2>

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 vti vti0 ipv6 accept-dad 2
set interfaces vti <interface> ipv6 dup-addr-detect-transmits <n>

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 vti vti0 ipv6 dup-addr-detect-transmits 5
set interfaces vti <interface> mtu <mtu>

Configure the MTU on the interface.

This value defines the largest packet size, in bytes, that the interface transmits without fragmentation.

Example:

set interfaces vti vti0 mtu 1600
set interfaces vti <interface> mirror egress <monitor-interface>

Configure mirroring of outgoing traffic from the specified VTI to the designated monitor interface.

set interfaces vti <interface> mirror ingress <monitor-interface>

Configure mirroring of incoming traffic from the specified VTI to the designated monitor interface.

set interfaces vti <interface> redirect <interface>

Enable redirection of incoming packets to the specified interface.

set interfaces vti <interface> vrf <vrf>

Assign the interface to a specific VRF instance.

See also

For information on configuring a VRF, refer to the VRF section.

Example:

set interfaces vti vti0 vrf red

Operation

show interfaces vti <vtiX>

Show the operational status and traffic statistics for the specified VTI.

show interfaces vti <vtiX> brief

Show a brief operational status summary for the specified VTI.

Example

Configure a VTI

Assign IPv4 and IPv6 addresses to the VTI, along with a brief description:

set interfaces vti vti0 address 192.168.2.249/30
set interfaces vti vti0 address 2001:db8:2::249/64
set interfaces vti vti0 description "Description"

Resulting configuration:

vyos@vyos# show interfaces vti
vti vti0 {
    address 192.168.2.249/30
    address 2001:db8:2::249/64
    description "Description"
}

Warning

When configuring site-to-site IPsec with VTIs, ensure that route autoinstall is disabled.

set vpn ipsec options disable-route-autoinstall

For more information about the IPsec and VTI issue, as well as the disable-route-autoinstall option, see: https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july.

The root cause of the problem is that VTI tunnels require their traffic selectors to be set to 0.0.0.0/0 for traffic to match the tunnel, even though routing decisions are based on netfilter marks. Unless route insertion is explicitly disabled, strongSWAN incorrectly inserts a default route through the VTI peer address, causing all traffic to be misrouted.