Router HSRP

HSRP is a first-hop redundancy protocol that enables multiple routers to share a virtual IP and MAC address, providing transparent failover for hosts without requiring router discovery. An active router handles forwarding while a standby router monitors its health and takes over seamlessly if the active router fails. IOS-XR supports HSRP on Ethernet interfaces, sub-interfaces, and link bundles, with IPv4 (version 1 and 2) and IPv6 (version 2) address families.

Diagram

Classes

iosxr

Name	Type	Constraint	Mandatory
devices	List	devices	No
device_groups	List	device_groups	No
global	Class	global	No

devices (iosxr)

Name	Type	Constraint	Mandatory	Default Value
configuration	Class	configuration	No

device_groups (iosxr)

Name	Type	Constraint	Mandatory	Default Value
configuration	Class	configuration	No

global (iosxr)

Name	Type	Constraint	Mandatory	Default Value
configuration	Class	configuration	No

configuration (iosxr.devices)

Name	Type	Constraint	Mandatory	Default Value
router_hsrp	Class	router_hsrp	No

router_hsrp (iosxr.devices.configuration)

Name	Type	Constraint	Mandatory	Default Value
interfaces	List	interfaces	No

interfaces (iosxr.devices.configuration.router_hsrp)

Name	Type	Constraint	Mandatory
name	String	Regex: `^(FastEthernet\|GigabitEthernet\|TenGigE\|TwentyFiveGigE\|FortyGigE\|FiftyGigE\| HundredGigE\|TwoHundredGigE\|FourHundredGigE\|EightHundredGigE\|BVI\|Bundle-Ether\| Bundle-POS\|CEM\|GCC[0-2]\|Loopback\|MgmtEth\|Multilink\|Null\|POS\|PW-Ether\|SRP\|lpts\| nve\|preconfigure\|tunnel-ip\|tunnel-ipsec\|tunnel-mte\|tunnel-te\|tunnel-tp)\d+(/\d+)*(\.\d+)?$`	Yes
use_bia	Boolean	`true`, `false`	No
redirects_disable	Boolean	`true`, `false`	No
delay_minimum	Integer	min: `0`, max: `10000`	No
delay_reload	Integer	min: `0`, max: `10000`	No
bfd_minimum_interval	Integer	min: `3`, max: `30000`	No
bfd_multiplier	Integer	min: `2`, max: `50`	No
mac_refresh	Integer	min: `0`, max: `10000`	No
ipv4	List	ipv4	No
ipv6	List	ipv6	No

ipv4 (iosxr.devices.configuration.router_hsrp.interfaces)

Name	Type	Constraint	Mandatory
group	Integer	min: `0`, max: `4095`	Yes
version	Choice	`1`, `2`	No
address	IP		No
address_learn	Boolean	`true`, `false`	No
priority	Integer	min: `0`, max: `255`	No
preempt_delay	Integer	min: `0`, max: `3600`	No
timers_seconds	Integer	min: `1`, max: `255`	No
timers_seconds_holdtime	Integer	min: `1`, max: `255`	No
timers_msec	Integer	min: `100`, max: `3000`	No
timers_msec_holdtime	Integer	min: `100`, max: `3000`	No
mac_address	String		No
name	String		No
bfd_fast_detect_peer_ipv4	IP		No
bfd_fast_detect_peer_interface	String	Regex: `^(FastEthernet\|GigabitEthernet\|TenGigE\|TwentyFiveGigE\|FortyGigE\|FiftyGigE\| HundredGigE\|TwoHundredGigE\|FourHundredGigE\|EightHundredGigE\|BVI\|Bundle-Ether\| Bundle-POS\|CEM\|GCC[0-2]\|Loopback\|MgmtEth\|Multilink\|Null\|POS\|PW-Ether\|SRP\|lpts\| nve\|preconfigure\|tunnel-ip\|tunnel-ipsec\|tunnel-mte\|tunnel-te\|tunnel-tp)\s?\d+(/[A-Z0-9]+)*(\.\d+)?$`	No
secondary_ipv4_addresses	List	secondary_ipv4_addresses	No
track_interfaces	List	track_interfaces	No
track_objects	List	track_objects	No

ipv6 (iosxr.devices.configuration.router_hsrp.interfaces)

Name	Type	Constraint	Mandatory
group	Integer	min: `0`, max: `4095`	Yes
addresses	List	addresses	No
linklocal_address	IP		No
linklocal_address_autoconfig	Boolean	`true`, `false`	No
linklocal_address_autoconfig_legacy	Boolean	`true`, `false`	No
priority	Integer	min: `0`, max: `255`	No
preempt_delay	Integer	min: `0`, max: `3600`	No
timers_seconds	Integer	min: `1`, max: `255`	No
timers_seconds_holdtime	Integer	min: `1`, max: `255`	No
timers_msec	Integer	min: `100`, max: `3000`	No
timers_msec_holdtime	Integer	min: `100`, max: `3000`	No
mac_address	String		No
name	String		No
bfd_fast_detect_peer_ipv6	IP		No
bfd_fast_detect_peer_interface	String	Regex: `^(FastEthernet\|GigabitEthernet\|TenGigE\|TwentyFiveGigE\|FortyGigE\|FiftyGigE\| HundredGigE\|TwoHundredGigE\|FourHundredGigE\|EightHundredGigE\|BVI\|Bundle-Ether\| Bundle-POS\|CEM\|GCC[0-2]\|Loopback\|MgmtEth\|Multilink\|Null\|POS\|PW-Ether\|SRP\|lpts\| nve\|preconfigure\|tunnel-ip\|tunnel-ipsec\|tunnel-mte\|tunnel-te\|tunnel-tp)\s?\d+(/[A-Z0-9]+)*(\.\d+)?$`	No
track_interfaces	List	track_interfaces	No
track_objects	List	track_objects	No

secondary_ipv4_addresses (iosxr.devices.configuration.router_hsrp.interfaces.ipv4)

Name	Type	Constraint	Mandatory	Default Value
address	IP		Yes

track_interfaces (iosxr.devices.configuration.router_hsrp.interfaces.ipv4)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
priority_decrement	Integer	min: `1`, max: `255`	Yes

track_objects (iosxr.devices.configuration.router_hsrp.interfaces.ipv4)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
priority_decrement	Integer	min: `1`, max: `255`	Yes

addresses (iosxr.devices.configuration.router_hsrp.interfaces.ipv6)

Name	Type	Constraint	Mandatory	Default Value
address	IP		Yes

track_interfaces (iosxr.devices.configuration.router_hsrp.interfaces.ipv6)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
priority_decrement	Integer	min: `1`, max: `255`	Yes

track_objects (iosxr.devices.configuration.router_hsrp.interfaces.ipv6)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
priority_decrement	Integer	min: `1`, max: `255`	Yes

Guidelines and Limitations

Version Routing

The version field on IPv4 groups controls which HSRP version is used. If version is omitted, it defaults to 2.

version: 1 — Group ID range 0-255, maps to HSRP version 1
version: 2 (default) — Group ID range 0-4095, maps to HSRP version 2

IPv6 groups are always version 2; the version field is not applicable and should be omitted.

Data Normalization

MAC Address Formats

Fields that accept MAC addresses can be in any of three formats:

colon-separated (e.g., "01:01:01:01:01:01")
dash-separated (e.g., "01-01-01-01-01-01")
dotted (e.g., "0101.0101.0101")

All 3 formats can be used interchangeably. The normalization layer converts the user-specified format to colon-separated before sending to the device.

Example YAML Code:

Example-1: Active/standby gateway pair on a data center VLAN interface with BFD-accelerated failover and uplink tracking

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        router_hsrp:
          interfaces:
            - name: Bundle-Ether10.100
              redirects_disable: true
              delay_minimum: 300
              delay_reload: 600
              bfd_minimum_interval: 15000
              bfd_multiplier: 3
              mac_refresh: 3600
              ipv4:
                - group: 100
                  version: 2
                  address: 172.16.100.1
                  priority: 150
                  preempt_delay: 180
                  timers_msec: 250
                  timers_msec_holdtime: 750
                  name: DC_VLAN100_GW
                  bfd_fast_detect_peer_ipv4: 172.16.100.3
                  bfd_fast_detect_peer_interface: Bundle-Ether10.100
                  secondary_ipv4_addresses:
                    - address: 172.16.100.2
                  track_interfaces:
                    - name: TenGigE0/0/0/0
                      priority_decrement: 60
                  track_objects:
                    - name: UPSTREAM_REACHABILITY
                      priority_decrement: 80

Example-2: Dual-stack with IPv4 and IPv6 HSRP on the same interface

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        router_hsrp:
          interfaces:
            - name: TenGigE0/0/0/1.200
              delay_minimum: 200
              delay_reload: 400
              bfd_minimum_interval: 15000
              bfd_multiplier: 3
              ipv4:
                - group: 200
                  address: 10.200.0.1
                  priority: 120
                  preempt_delay: 60
                  timers_seconds: 3
                  timers_seconds_holdtime: 10
                  name: V200
                  track_interfaces:
                    - name: TenGigE0/0/0/0
                      priority_decrement: 30
              ipv6:
                - group: 200
                  addresses:
                    - address: "2001:db8:200::1"
                  linklocal_address: "fe80::1"
                  priority: 120
                  preempt_delay: 60
                  timers_seconds: 3
                  timers_seconds_holdtime: 10
                  name: V200_V6
                  track_interfaces:
                    - name: TenGigE0/0/0/0
                      priority_decrement: 30

Example-3: Single IPv4 gateway with default version (2)

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        router_hsrp:
          interfaces:
            - name: GigabitEthernet0/0/0/0
              ipv4:
                - group: 1
                  address: 192.168.1.1
                  priority: 110