Tunnel

Tunnel interfaces provide virtual point-to-point connections across IP networks, enabling secure communication, network extension, and overlay services through various encapsulation protocols including GRE, IPsec, and MPLS over IP. They support multiple tunnel types for different use cases such as site-to-site VPNs, dynamic routing over WANs, traffic engineering, and network virtualization while maintaining full Layer 3 functionality with routing protocol support and quality of service capabilities. Tunnel interfaces are essential for connecting remote sites, extending private networks across public infrastructure, implementing overlay networks, and providing secure communication channels that abstract the underlying physical network topology.

Diagram

Classes

interfaces (iosxe.devices.configuration)

Name	Type	Constraint	Mandatory	Default Value
tunnels	List	[tunnels]	No

tunnels (iosxe.devices.configuration.interfaces)

Name	Type	Constraint	Mandatory	Default Value
name	Integer		Yes
interface_groups	List	String	No
interface_group_policy	Choice	merge, replace	No
description	String		No
shutdown	Boolean	true, false	No
vrf_forwarding	String		No
ipv4	Class	[ipv4]	No
ipv6	Class	[ipv6]	No
bfd	Class	[bfd]	No
tunnel_destination_ipv4	IP		No
ospf	Class	[ospf]	No
ospfv3	Class	[ospfv3]	No
pim	Class	[pim]	No
igmp	Class	[igmp]	No
arp_timeout	Integer	min: 0, max: 2147483	No
bandwidth	Integer	min: 1, max: 200000000	No
ip_mtu	Integer	min: 576, max: 1500	No
load_interval	Integer	min: 30, max: 600	No
snmp_trap_link_status	Boolean	true, false	No
logging_event_link_status_enable	Boolean	true, false	No
tunnel_vrf	String		No
tunnel_mode_ipsec_ipv4	Boolean	true, false	No
tunnel_mode_gre_multipoint	Boolean	true, false	No
tunnel_protection_ipsec_profile	String		No
tunnel_source	String		No
tunnel_key	Integer	min: 0, max: 4294967295	No
tunnel_bandwidth_transmit	Integer	min: 1, max: 10000000	No
tunnel_bandwidth_receive	Integer	min: 1, max: 10000000	No
ip_nhrp_authentication	String		No
ip_nhrp_network_id	Integer	min: 1, max: 4294967295	No
ip_nhrp_nhs	List	[ip_nhrp_nhs]	No
ip_nhrp_maps	List	[ip_nhrp_maps]	No
ip_nhrp_redirect	Boolean	true, false	No
ip_nhrp_shortcut	Boolean	true, false	No
mpls_nhrp	Boolean	true, false	No
service_policy_input	String		No
service_policy_output	String		No
zone_member_security	String		No

ipv4 (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
address	IP		No
address_mask	IP		No
proxy_arp	Boolean	true, false	No
dhcp_relay_source_interface_type	Choice	Loopback, Vlan, GigabitEthernet, TwoGigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, TwentyFiveGigabitEthernet, FortyGigabitEthernet, FiftyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
dhcp_relay_source_interface_id	Any	String or Integer[min: 0]	No
helper_addresses	List	[helper_addresses]	No
access_group_in	String		No
access_group_out	String		No
flow_monitors	List	[flow_monitors]	No
redirects	Boolean	true, false	No
unreachables	Boolean	true, false	No
unnumbered_interface_type	Choice	Loopback, Vlan, GigabitEthernet, TwoGigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, TwentyFiveGigabitEthernet, FortyGigabitEthernet, FiftyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
unnumbered_interface_id	Any	String or Integer[min: 0]	No
nat_inside	Boolean	true, false	No
nat_outside	Boolean	true, false	No
address_dhcp	Boolean	true, false	No

ipv6 (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
enable	Boolean	true, false	No
addresses	List	[addresses]	No
link_local_addresses	List	IP	No
address_autoconfig_default	Boolean	true, false	No
address_dhcp	Boolean	true, false	No
mtu	Integer	min: 1280, max: 9976	No
nd_ra_suppress_all	Boolean	true, false	No
flow_monitors	List	[flow_monitors]	No
pim	Class	[pim]	No

bfd (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
template	String		No
enable	Boolean	true, false	No
local_address	IP		No
interval	Integer	min: 50, max: 9999	No
interval_min_rx	Integer	min: 50, max: 9999	No
interval_multiplier	Integer	min: 3, max: 50	No
echo	Boolean	true, false	No

ospf (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
authentication_key_chain	String		No
authentication_message_digest	Boolean	true, false	No
authentication_null	Boolean	true, false	No
cost	Integer	min: 1, max: 65535	No
dead_interval	Integer	min: 1, max: 65535	No
hello_interval	Integer	min: 1, max: 65535	No
message_digest_keys	List	[message_digest_keys]	No
mtu_ignore	Boolean	true, false	No
multi_area_ids	List	Any[String or Integer[min: 0]]	No
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
priority	Integer	min: 0, max: 255	No
process_ids	List	[process_ids]	No
ttl_security_hops	Integer	min: 1, max: 254	No

ospfv3 (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
bfd	Boolean	true, false	No
cost	Integer	min: 1, max: 65535	No
dead_interval	Integer	min: 1, max: 65535	No
hello_interval	Integer	min: 1, max: 65535	No
mtu_ignore	Boolean	true, false	No
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
priority	Integer	min: 0, max: 255	No

pim (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
passive	Boolean	true, false	No
dense_mode	Boolean	true, false	No
sparse_mode	Boolean	true, false	No
sparse_dense_mode	Boolean	true, false	No
bfd	Boolean	true, false	No
border	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967294	No

igmp (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
version	Integer	min: 1, max: 3	No

ip_nhrp_nhs (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
ipv4	IP		Yes

ip_nhrp_maps (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
dest_ipv4	IP		Yes
nbma_ipv4	IP		Yes

helper_addresses (iosxe.devices.configuration.interfaces.tunnels.ipv4)

Name	Type	Constraint	Mandatory	Default Value
address	IP		Yes
global	Boolean	true, false	No
vrf	String		No

flow_monitors (iosxe.devices.configuration.interfaces.tunnels.ipv4)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
direction	Choice	input, output	Yes

addresses (iosxe.devices.configuration.interfaces.tunnels.ipv6)

Name	Type	Constraint	Mandatory	Default Value
prefix	IP		Yes
eui_64	Boolean	true, false	No

pim (iosxe.devices.configuration.interfaces.tunnels.ipv6)

Name	Type	Constraint	Mandatory	Default Value
pim	Boolean	true, false	No
bfd	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967295	No

message_digest_keys (iosxe.devices.configuration.interfaces.tunnels.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 255	Yes
md5_auth_key	String		No
md5_auth_type	Choice	0, 7	No

process_ids (iosxe.devices.configuration.interfaces.tunnels.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 65535	No
areas	List	Any[String or Integer[min: 0]]	No

Guidelines and Limitations

IP Address Reassignment Between Interfaces

IOS-XE enforces IP address uniqueness within the same VRF — no two interfaces can hold the same IP address simultaneously. When swapping IP addresses between two interfaces (for example, moving 10.1.1.1 from Tunnel100 to Tunnel200 and vice versa), terraform apply will fail because Terraform updates both interfaces in parallel without awareness of the cross-resource conflict. The device rejects the new IP assignment with an “inconsistent value: Device refused one or more commands” error because the target IP still exists on the other interface.

To perform an IP swap, apply the change in two steps:

1. Remove the IP addresses from both interfaces (delete the ipv4 block or assign temporary addresses) and run terraform apply.
2. Set the new desired IP addresses and run terraform apply a second time.

Examples

Basic GRE Tunnel with IPv4 and BFD

This example attaches the flow monitor FLOW1 to the tunnel for brevity. The supporting flow record, flow exporter, and flow monitor resources must be defined under the device’s flow section before they can be referenced here — see Example 4 below for a complete declaration.

Cisco IOS-XE CLI Equivalent:

interface Tunnel100
 description GRE Tunnel to Remote Site
 no shutdown
 vrf forwarding WAN
 tunnel destination 203.0.113.10
 tunnel source GigabitEthernet0/0/1
 ip address 10.255.1.1 255.255.255.252
 no ip redirects
 no ip unreachables
 ipv6 address 2001:db8:tunnel::1/64
 bfd enable
 bfd interval 100 min_rx 100 multiplier 3
 ip ospf cost 1000
 ip ospf network point-to-point
 ip ospf 1 area 0
 ip flow monitor FLOW1 input
 load-interval 30
 ip mtu 1476
 ip pim sparse-mode
 ip igmp version 2

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - name: 100
              interface_groups: [TUNNEL_BASE_CONFIG]
              description: GRE Tunnel to Remote Site
              shutdown: false
              vrf_forwarding: WAN
              tunnel_destination_ipv4: 203.0.113.10
              tunnel_source: GigabitEthernet0/0/1
              tunnel_mode_ipsec_ipv4: false
              arp_timeout: 3600
              ipv4:
                address: 10.255.1.1
                address_mask: 255.255.255.252
                address_dhcp: true
                redirects: false
                unreachables: false
                flow_monitors:
                  - name: FLOW1
                    direction: input
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:tunnel::1/64
              bfd:
                enable: true
                interval: 100
                interval_multiplier: 3
              ospf:
                cost: 1000
                network_type: point-to-point
                process_ids:
                  - id: 1
                    areas:
                      - "0"
              load_interval: 30
              ip_mtu: 1476
              pim:
                sparse_mode: true
              igmp:
                version: 2

IPsec VPN Tunnel with IPv6

Cisco IOS-XE CLI Equivalent:

interface Tunnel200
 description IPsec VPN Tunnel
 no shutdown
 bandwidth 500000
 tunnel destination 198.51.100.20
 tunnel source GigabitEthernet0/0/0
 tunnel vrf INTERNET
 tunnel bandwidth transmit 2000
 tunnel bandwidth receive 2000
 ip address 172.16.255.1 255.255.255.252
 ipv6 address dhcp
 logging event link-status
 snmp trap link-status
 tunnel mode ipsec ipv4
 tunnel protection ipsec profile IPSEC-PROFILE-1
 service-policy input QOS-IN
 service-policy output QOS-OUT

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - name: 200
              description: IPsec VPN Tunnel
              shutdown: false
              bandwidth: 500000
              tunnel_destination_ipv4: 198.51.100.20
              tunnel_source: GigabitEthernet0/0/0
              tunnel_mode_ipsec_ipv4: true
              tunnel_protection_ipsec_profile: IPSEC-PROFILE-1
              tunnel_vrf: INTERNET
              tunnel_bandwidth_transmit: 2000
              tunnel_bandwidth_receive: 2000
              service_policy_input: QOS-IN
              service_policy_output: QOS-OUT
              ipv4:
                address: 172.16.255.1
                address_mask: 255.255.255.252
              ipv6:
                enable: true
                address_dhcp: true
              logging_event_link_status_enable: true
              snmp_trap_link_status: true

Sample Configuration

Example 1: Tunnel Interface with Interface Groups

Example configuring a GRE tunnel interface using an interface group. The interface_groups attribute is a NAC abstraction that applies shared configuration from a named group at template render time. The resulting device CLI reflects the fully merged configuration - interface_groups does not appear as a CLI command.

Cisco IOS-XE CLI Equivalent:

interface Tunnel100
 description Tunnel for Interface Groups Documentation
 ip address 10.255.1.1 255.255.255.252
 ip mtu 1476
 tunnel source GigabitEthernet1/0/1
 tunnel destination 203.0.113.10

NAC YAML Configuration:

iosxe:
  interface_groups:
    - name: TUNNEL_BASE_CONFIG
      configuration:
        description: "Tunnel for Interface Groups Documentation"
        ip_mtu: 1476
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - name: 100
              interface_groups: [TUNNEL_BASE_CONFIG]
              tunnel_destination_ipv4: 203.0.113.10
              tunnel_source: GigabitEthernet1/0/1
              ipv4:
                address: 10.255.1.1
                address_mask: 255.255.255.252

Example 2: Tunnel Interface with QoS (Bandwidth and Service-Policy)

Example configuring a tunnel interface with bandwidth settings and QoS service-policy attachment.

Cisco IOS-XE CLI Equivalent:

interface Tunnel100
 description QoS Tunnel
 ip address 10.100.100.1 255.255.255.252
 bandwidth 1000000
 tunnel source GigabitEthernet1/0/1
 tunnel destination 192.0.2.1
 tunnel bandwidth transmit 5000
 tunnel bandwidth receive 5000
 service-policy input INGRESS-POLICY
 service-policy output EGRESS-POLICY

NAC YAML Configuration:

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - name: 100
              description: QoS Tunnel
              tunnel_destination_ipv4: 192.0.2.1
              tunnel_source: GigabitEthernet1/0/1
              bandwidth: 1000000
              tunnel_bandwidth_transmit: 5000
              tunnel_bandwidth_receive: 5000
              service_policy_input: INGRESS-POLICY
              service_policy_output: EGRESS-POLICY
              ipv4:
                address: 10.100.100.1
                address_mask: 255.255.255.252

Example 3: Tunnel Interface with Custom ARP Timeout

Example configuring a GRE tunnel interface with a custom ARP cache timeout. Note that arp timeout only appears in show run output when set to a non-default value. The default ARP timeout is 14400 seconds (4 hours).

Cisco IOS-XE CLI Equivalent:

interface Tunnel100
 description Test Tunnel for arp_timeout doc validation
 ip address 10.100.100.1 255.255.255.252
 arp timeout 3600
 ip mtu 1476
 tunnel source GigabitEthernet1/0/1
 tunnel destination 192.0.2.1

NAC YAML Configuration:

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - name: 100
              description: Test Tunnel for arp_timeout doc validation
              tunnel_destination_ipv4: 192.0.2.1
              tunnel_source: GigabitEthernet1/0/1
              arp_timeout: 3600
              ip_mtu: 1476
              ipv4:
                address: 10.100.100.1
                address_mask: 255.255.255.252

Example 3: Tunnel Interface with IPv6 and OSPFv3

Example configuring a tunnel interface with IPv6 addressing, link-local address, and OSPFv3 routing.

Cisco IOS-XE CLI Equivalent:

interface Tunnel200
 description IPv6 Tunnel with OSPFv3
 tunnel destination 192.0.2.2
 tunnel source 10.0.0.1
 ip unnumbered Loopback0
 ipv6 enable
 ipv6 address 2001:db8:100::/64 eui-64
 ipv6 address fe80::1 link-local
 ipv6 mtu 1400
 ospfv3 network point-to-point
 ospfv3 cost 150
 bfd enable
 bfd interval 150 min_rx 150 multiplier 5

NAC YAML Configuration:

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          loopbacks:
            - name: 0
              ipv4:
                address: "10.0.0.1"
                address_mask: "255.255.255.255"
          tunnels:
            - name: 200
              description: "IPv6 Tunnel with OSPFv3"
              tunnel_destination_ipv4: "192.0.2.2"
              tunnel_source: "10.0.0.1"
              ipv4:
                unnumbered_interface_type: "Loopback"
                unnumbered_interface_id: "0"
              ipv6:
                enable: true
                addresses:
                  - prefix: "2001:db8:100::/64"
                    eui_64: true
                link_local_addresses:
                  - "fe80::1"
                mtu: 1400
              ospfv3:
                network_type: "point-to-point"
                cost: 150
                bfd: true
                dead_interval: 40
                hello_interval: 10
                mtu_ignore: true
                priority: 100
              bfd:
                enable: true
                interval: 150
                interval_min_rx: 150
                interval_multiplier: 5

Example 4: Tunnel Interface with Flow Monitors

Example configuring tunnel interfaces with IPv4 and IPv6 NetFlow flow monitors. Flow monitors require supporting flow record, exporter, and monitor resources to be defined under the flow configuration section. Each flow monitor is applied with a direction (input or output). Separate records and monitors are defined for IPv4 and IPv6 because the match fields differ per address family; the exporter is shared.

Cisco IOS-XE CLI Equivalent:

flow record TUNNEL-FLOW-RECORD-V4
 match ipv4 source address
 match ipv4 destination address
 match ipv4 protocol
 match transport source-port
 match transport destination-port
 collect counter bytes long
 collect counter packets long
flow record TUNNEL-FLOW-RECORD-V6
 match ipv6 source address
 match ipv6 destination address
 match ipv6 protocol
 match transport source-port
 match transport destination-port
 collect counter bytes long
 collect counter packets long
flow exporter TUNNEL-FLOW-EXPORTER
 destination 10.1.1.200
 transport udp 9995
 export-protocol netflow-v9
flow monitor TUNNEL-FLOW-MONITOR-V4
 record TUNNEL-FLOW-RECORD-V4
 exporter TUNNEL-FLOW-EXPORTER
 cache timeout active 60
 cache timeout inactive 30
flow monitor TUNNEL-FLOW-MONITOR-V6
 record TUNNEL-FLOW-RECORD-V6
 exporter TUNNEL-FLOW-EXPORTER
 cache timeout active 60
 cache timeout inactive 30
interface Tunnel200
 description Tunnel IPv4 flow monitor input
 ip address 10.200.200.1 255.255.255.0
 ip flow monitor TUNNEL-FLOW-MONITOR-V4 input
interface Tunnel201
 description Tunnel IPv4 flow monitor output
 ip address 10.201.201.1 255.255.255.0
 ip flow monitor TUNNEL-FLOW-MONITOR-V4 output
interface Tunnel202
 description Tunnel IPv6 flow monitor input
 ipv6 enable
 ipv6 address 2001:db8:202::1/64
 ipv6 flow monitor TUNNEL-FLOW-MONITOR-V6 input
interface Tunnel203
 description Tunnel IPv6 flow monitor output
 ipv6 enable
 ipv6 address 2001:db8:203::1/64
 ipv6 flow monitor TUNNEL-FLOW-MONITOR-V6 output

NAC YAML Configuration:

iosxe:
  devices:
    - name: Device1
      configuration:
        flow:
          records:
            - name: TUNNEL-FLOW-RECORD-V4
              description: IPv4 flow record for tunnel
              match:
                ipv4_source_address: true
                ipv4_destination_address: true
                ipv4_protocol: true
                transport_source_port: true
                transport_destination_port: true
              collect:
                counter_bytes_long: true
                counter_packets_long: true
            - name: TUNNEL-FLOW-RECORD-V6
              description: IPv6 flow record for tunnel
              match:
                ipv6_source_address: true
                ipv6_destination_address: true
                ipv6_protocol: true
                transport_source_port: true
                transport_destination_port: true
              collect:
                counter_bytes_long: true
                counter_packets_long: true
          exporters:
            - name: TUNNEL-FLOW-EXPORTER
              destination_ip: 10.1.1.200
              transport_udp: 9995
              export_protocol: netflow-v9
          monitors:
            - name: TUNNEL-FLOW-MONITOR-V4
              record: TUNNEL-FLOW-RECORD-V4
              exporters:
                - TUNNEL-FLOW-EXPORTER
              cache_timeout_active: 60
              cache_timeout_inactive: 30
            - name: TUNNEL-FLOW-MONITOR-V6
              record: TUNNEL-FLOW-RECORD-V6
              exporters:
                - TUNNEL-FLOW-EXPORTER
              cache_timeout_active: 60
              cache_timeout_inactive: 30
        interfaces:
          tunnels:
            - name: 200
              description: Tunnel IPv4 flow monitor input
              ipv4:
                address: 10.200.200.1
                address_mask: 255.255.255.0
                flow_monitors:
                  - name: TUNNEL-FLOW-MONITOR-V4
                    direction: input
            - name: 201
              description: Tunnel IPv4 flow monitor output
              ipv4:
                address: 10.201.201.1
                address_mask: 255.255.255.0
                flow_monitors:
                  - name: TUNNEL-FLOW-MONITOR-V4
                    direction: output
            - name: 202
              description: Tunnel IPv6 flow monitor input
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:202::1/64
                flow_monitors:
                  - name: TUNNEL-FLOW-MONITOR-V6
                    direction: input
            - name: 203
              description: Tunnel IPv6 flow monitor output
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:203::1/64
                flow_monitors:
                  - name: TUNNEL-FLOW-MONITOR-V6
                    direction: output

Example 5: DMVPN Tunnel with NHRP and GRE Multipoint

Example configuring a DMVPN hub tunnel interface with NHRP and GRE multipoint mode. DMVPN uses NHRP for dynamic spoke-to-spoke tunnel creation and GRE multipoint for single tunnel interface supporting multiple endpoints. The tunnel_mode_gre_multipoint attribute sets the tunnel mode to gre multipoint. NHRP attributes include authentication, network-id, NHS (next hop server) addresses, static maps, and redirect/shortcut for spoke-to-spoke optimization. The mpls_nhrp attribute enables MPLS over NHRP for label distribution across DMVPN overlays.

Note: When creating a DMVPN tunnel for the first time with tunnel_key or mpls_nhrp alongside tunnel_mode_gre_multipoint, the initial terraform apply may fail. IOS-XE requires GRE multipoint mode to be active before it accepts tunnel key or mpls nhrp commands, but the device’s NETCONF-to-CLI translation processes these commands in an internal order that cannot be controlled externally. A second terraform apply will succeed because the tunnel mode is already set from the first (partially successful) apply.

Cisco IOS-XE CLI Equivalent:

interface Tunnel100
 description DMVPN Hub Tunnel
 ip address 10.0.0.1 255.255.255.0
 ip nhrp authentication SECRET
 ip nhrp network-id 100
 ip nhrp nhs 10.0.0.254
 ip nhrp map 10.0.0.2 172.16.1.2
 ip nhrp redirect
 ip nhrp shortcut
 mpls nhrp
 tunnel source GigabitEthernet1
 tunnel mode gre multipoint
 tunnel key 10

NAC YAML Configuration:

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - name: 100
              description: DMVPN Hub Tunnel
              tunnel_source: GigabitEthernet1
              tunnel_mode_gre_multipoint: true
              tunnel_key: 10
              ip_nhrp_authentication: SECRET
              ip_nhrp_network_id: 100
              ip_nhrp_nhs:
                - ipv4: 10.0.0.254
              ip_nhrp_maps:
                - dest_ipv4: 10.0.0.2
                  nbma_ipv4: 172.16.1.2
              ip_nhrp_redirect: true
              ip_nhrp_shortcut: true
              mpls_nhrp: true
              ipv4:
                address: 10.0.0.1
                address_mask: 255.255.255.0

Example 6: Tunnel Interface with PIM Attributes

Example configuring tunnel interfaces with the full set of IPv4 PIM attributes and IPv6 PIM. PIM requires global multicast routing to be enabled under the device’s system section. The passive, dense_mode, sparse_mode, and sparse_dense_mode attributes are mutually exclusive — pick one mode per tunnel. The remaining attributes (bfd, border, bsr_border, dr_priority) modify behavior and are typically combined with sparse_mode. IPv6 PIM is configured under ipv6.pim and supports pim, bfd, bsr_border, and dr_priority.

Cisco IOS-XE CLI Equivalent:

ip multicast-routing distributed
ipv6 unicast-routing
ipv6 multicast-routing
interface Tunnel300
 description Tunnel with IPv4 PIM sparse-mode and BFD
 ip address 10.30.0.1 255.255.255.252
 tunnel source GigabitEthernet1
 tunnel destination 192.0.2.30
 ip pim sparse-mode
 ip pim bfd
 ip pim dr-priority 100
 ip pim bsr-border
interface Tunnel301
 description Tunnel with IPv6 PIM
 tunnel source GigabitEthernet1
 tunnel destination 192.0.2.31
 ipv6 enable
 ipv6 address 2001:db8:301::1/64
 ipv6 pim
 ipv6 pim dr-priority 50

NAC YAML Configuration:

iosxe:
  devices:
    - name: Device1
      configuration:
        system:
          ip_multicast_routing: true
          ip_multicast_routing_distributed: true
          ipv6_unicast_routing: true
          ipv6_multicast_routing: true
        interfaces:
          tunnels:
            - name: 300
              description: Tunnel with IPv4 PIM sparse-mode and BFD
              tunnel_destination_ipv4: 192.0.2.30
              tunnel_source: GigabitEthernet1
              ipv4:
                address: 10.30.0.1
                address_mask: 255.255.255.252
              pim:
                sparse_mode: true
                bfd: true
                bsr_border: true
                dr_priority: 100
            - name: 301
              description: Tunnel with IPv6 PIM
              tunnel_destination_ipv4: 192.0.2.31
              tunnel_source: GigabitEthernet1
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:301::1/64
                pim:
                  pim: true
                  dr_priority: 50

Tunnel interfaces provide virtual point-to-point connections across IP networks, enabling secure communication, network extension, and overlay services through various encapsulation protocols including GRE, IPsec, and MPLS over IP. They support multiple tunnel types for different use cases such as site-to-site VPNs, dynamic routing over WANs, traffic engineering, and network virtualization while maintaining full Layer 3 functionality with routing protocol support and quality of service capabilities. Tunnel interfaces are essential for connecting remote sites, extending private networks across public infrastructure, implementing overlay networks, and providing secure communication channels that abstract the underlying physical network topology.

Diagram

Classes

interfaces (iosxe.devices.configuration)

Name	Type	Constraint	Mandatory	Default Value
tunnels	List	[tunnels]	No

tunnels (iosxe.devices.configuration.interfaces)

Name	Type	Constraint	Mandatory	Default Value
name	Integer		Yes
interface_groups	List	String	No
description	String		No
shutdown	Boolean	true, false	No
vrf_forwarding	String		No
ipv4	Class	[ipv4]	No
ipv6	Class	[ipv6]	No
bfd	Class	[bfd]	No
tunnel_destination_ipv4	IP		No
ospf	Class	[ospf]	No
ospfv3	Class	[ospfv3]	No
igmp	Class	[igmp]	No
arp_timeout	Integer	min: 0, max: 2147483	No
ip_mtu	Integer	min: 576, max: 1500	No
load_interval	Integer	min: 30, max: 600	No
snmp_trap_link_status	Boolean	true, false	No
logging_event_link_status_enable	Boolean	true, false	No
tunnel_vrf	String		No
tunnel_mode_ipsec_ipv4	Boolean	true, false	No
tunnel_protection_ipsec_profile	String		No
tunnel_source	String		No

ipv4 (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
address	IP		No
address_mask	IP		No
proxy_arp	Boolean	true, false	No
arp_inspection_trust	Boolean	true, false	No
arp_inspection_limit_rate	Integer	min: 0, max: 4294967295	No
dhcp_snooping_trust	Boolean	true, false	No
dhcp_relay_source_interface_type	Choice	Loopback, Vlan, GigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, FortyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
dhcp_relay_source_interface_id	Any	String or Integer[min: 0]	No
dhcp_relay_information_option_vpn_id	Boolean	true, false	No
helper_addresses	List	[helper_addresses]	No
access_group_in	String		No
access_group_out	String		No
flow_monitors	List	[flow_monitors]	No
redirects	Boolean	true, false	No
unreachables	Boolean	true, false	No
unnumbered_interface_type	Choice	Loopback, Vlan, GigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, FortyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
unnumbered_interface_id	Any	String or Integer[min: 0]	No
nat_inside	Boolean	true, false	No
nat_outside	Boolean	true, false	No

ipv6 (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
enable	Boolean	true, false	No
addresses	List	[addresses]	No
link_local_addresses	List	IP	No
address_autoconfig_default	Boolean	true, false	No
address_dhcp	Boolean	true, false	No
mtu	Integer	min: 1280, max: 9976	No
nd_ra_suppress_all	Boolean	true, false	No
flow_monitors	List	[flow_monitors]	No
pim	Class	[pim]	No

bfd (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
template	String		No
enable	Boolean	true, false	No
local_address	String		No
interval	Integer	min: 50, max: 9999	No
interval_min_rx	Integer	min: 50, max: 9999	No
interval_multiplier	Integer	min: 3, max: 50	No
echo	Boolean	true, false	No

ospf (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
cost	Integer	min: 1, max: 65535	No
dead_interval	Integer	min: 1, max: 65535	No
hello_interval	Integer	min: 1, max: 65535	No
mtu_ignore	Boolean	true, false	No
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
priority	Integer	min: 0, max: 255	No
ttl_security_hops	Integer	min: 1, max: 254	No
process_ids	List	[process_ids]	No
message_digest_keys	List	[message_digest_keys]	No

ospfv3 (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
cost	Integer	min: 1, max: 65535	No

igmp (iosxe.devices.configuration.interfaces.tunnels)

Name	Type	Constraint	Mandatory	Default Value
version	Integer	min: 1, max: 3	No

helper_addresses (iosxe.devices.configuration.interfaces.tunnels.ipv4)

Name	Type	Constraint	Mandatory	Default Value
address	IP		Yes
global	Boolean	true, false	No
vrf	String		No

flow_monitors (iosxe.devices.configuration.interfaces.tunnels.ipv4)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
direction	Choice	input, output	Yes

addresses (iosxe.devices.configuration.interfaces.tunnels.ipv6)

Name	Type	Constraint	Mandatory	Default Value
prefix	IP		Yes
eui_64	Boolean	true, false	No

pim (iosxe.devices.configuration.interfaces.tunnels.ipv6)

Name	Type	Constraint	Mandatory	Default Value
pim	Boolean	true, false	No
bfd	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967295	No

process_ids (iosxe.devices.configuration.interfaces.tunnels.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 65535	No
areas	List	Any[String or Integer[min: 0]]	No

message_digest_keys (iosxe.devices.configuration.interfaces.tunnels.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 255	Yes
md5_auth_key	String		No
md5_auth_type	Choice	0, 7	No

Examples

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          tunnels:
            - id: 100
              description: GRE Tunnel to Remote Site
              shutdown: false
              vrf_forwarding: WAN
              tunnel_destination_ipv4: 203.0.113.10
              tunnel_source: GigabitEthernet0/0/1
              tunnel_mode_ipsec_ipv4: false
              ipv4:
                address: 10.255.1.1
                address_mask: 255.255.255.252
                redirects: false
                unreachables: false
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:tunnel::1/64
              bfd:
                enable: true
                interval: 100
                interval_multiplier: 3
              ospf:
                cost: 1000
                network_type: point-to-point
                process_ids:
                  - id: 1
                    areas:
                      - "0"
              load_interval: 30
              ip_mtu: 1476
              igmp:
                version: 2
            - id: 200
              description: IPsec VPN Tunnel
              shutdown: false
              tunnel_destination_ipv4: 198.51.100.20
              tunnel_source: GigabitEthernet0/0/0
              tunnel_mode_ipsec_ipv4: true
              tunnel_protection_ipsec_profile: IPSEC-PROFILE-1
              tunnel_vrf: INTERNET
              ipv4:
                address: 172.16.255.1
                address_mask: 255.255.255.252
              logging_event_link_status_enable: true
              snmp_trap_link_status: true