OSPFv3 troubleshooting — neighbour stuck, link-local issues, LSDB inconsistencies, IPv6 ACLs

OSPFv3 troubleshooting looks like OSPFv2 troubleshooting with longer addresses. It is not. The protocol redesign introduces new failure modes — link-local address mismatches, IPv6 firewall rules dropping OSPFv3 control packets, Type 8 / Type 9 LSA inconsistencies — that have no OSPFv2 equivalent.

This lesson covers the OSPFv3-specific diagnostic playbook: the neighbour-stuck state machine, the link-local address rule, the IPv6 firewall interaction, the LSDB consistency checks, and the rollback path.

The OSPFv3 diagnostic command set

show ipv6 ospf6
show ipv6 ospf6 neighbor
show ipv6 ospf6 neighbor detail
show ipv6 ospf6 interface
show ipv6 ospf6 database
show ipv6 ospf6 database router
show ipv6 ospf6 database link
show ipv6 ospf6 database intra-prefix
show ipv6 ospf6 database external
show ipv6 ospf6 database verbose
show ipv6 ospf6 border-routers
show ipv6 route ospf6
show ipv6 ospf6 statistics
tcpdump -ni eth0 proto ospf6
debug ospf6 adj
debug ospf6 lsa
debug ospf6 zebra
vtysh -c show ipv6 ospf6

The debug ospf6 ... commands enable verbose logging in FRR. The output is large (a single adjacency formation can produce hundreds of log lines); the operator enables them sparingly and only on the affected router.

Failure mode 1 — Neighbour stuck because of link-local mismatch

The most common OSPFv3 adjacency failure is the neighbour-stuck state. The OSPFv3 Hello packets are sourced from the link-local address fe80::<interface-id>. If the link-local on the local interface does not match what the neighbour expects, the adjacency fails.

The diagnostic:

show ipv6 ospf6 neighbor
# Neighbor ID     Pri   DeadTime  State/IfState         I/fState Duration
# (empty)

show ipv6 ospf6 interface eth0
# Interface eth0
#   Link-local address: fe80::1
#   Area 0, MTU 1500

ip -6 addr show eth0
# link/ether ... 
# inet6 fe80::1/64 scope link

The neighbour is not visible. The local interface has its link-local. The neighbour is not receiving the Hello packets (or the neighbour’s Hello packets are not being processed).

sequenceDiagram
  participant R1
  participant R2
  Note over R1,R2: Both send Hello<br/>Both send to ff02::5
  R1->>R2: Hello src=fe80::1 dst=ff02::5
  R2->>R1: Hello src=fe80::2 dst=ff02::5
  Note over R1,R2: Link-local matches<br/>Area matches<br/>Timers match<br/>Adjacency forms

The common link-local failure modes:

• Link-local is filtered. An IPv6 firewall rule drops packets from fe80::/64 because the operator wrote a global-unicast-only rule. The Hello packets are silently dropped.
• Link-local changes after interface bounce. If the operator disables and re-enables the interface, the link-local may change. The neighbour has the old link-local cached and refuses to form a new adjacency.
• Duplicate link-local. Two routers on the same link have the same link-local (rare but happens with misconfigured EUI-64). The router’s NDP table picks one as the active neighbour; the OSPFv3 Hello from the other is rejected.

The diagnostic for filtered link-local:

tcpdump -ni eth0 proto ospf6
# (empty output suggests packets are not arriving on the wire)

# Check the IPv6 firewall rules
show firewall ipv6 name WAN-LOCAL
# rule 10 action accept
# rule 10 protocol ipv6-icmp
# rule 10 source address fe80::/64
# ...

The fix is to add an IPv6 firewall rule that accepts OSPFv3 control packets (the protocol number is 89, the same as OSPFv2; OSPFv3 is “OSPF for IPv6” and uses IP protocol 89).

set firewall ipv6 name WAN-LOCAL rule 10 action accept
set firewall ipv6 name WAN-LOCAL rule 10 protocol ospf
set firewall ipv6 name WAN-LOCAL rule 10 source address fe80::/64
set firewall ipv6 name WAN-LOCAL rule 10 destination address ff02::5
commit
save

Failure mode 2 — Area mismatch on OSPFv3 interfaces

The area assignment on OSPFv3 is per-interface. If R1 has eth0 in area 0 but R2 has eth0 in area 1, the adjacency fails. The OSPFv3 Hello packets are accepted (they share the same OSPFv3 multicast group) but the area-id check fails.

The diagnostic:

show ipv6 ospf6 neighbor
# (empty)

show ipv6 ospf6 interface eth0
# Interface eth0
#   Area 0

# On the neighbour:
show ipv6 ospf6 interface eth0
# Interface eth0
#   Area 1

The fix is to align the area-id on both sides:

# On R2
delete protocols ospfv3 area 1 interface eth0
set protocols ospfv3 area 0 interface eth0
commit
save

The same diagnostic applies to instance-id mismatches. If R1 has instance-id 0 (default) and R2 has instance-id 1, the Hello packets are not considered to be from the same OSPFv3 process; the adjacency fails.

Failure mode 3 — LSDB inconsistencies on Type 8 / Type 9

The Type 8 Link-LSA is flooded only on the local link. The Type 9 Intra-Area-Prefix-LSA is flooded area-wide. If either is missing, the routing table diverges.

The diagnostic for Type 9:

show ipv6 ospf6 database intra-prefix self-originate verbose
# Type 9 LSAs originated by this router, with prefix and referenced Type 1 LSA

If a Type 9 is missing, the prefix is not advertised to the area. The remote router has the Type 1 (topology) but no Type 9 (prefix); it cannot install the route.

The diagnostic for Type 8:

show ipv6 ospf6 database link self-originate verbose
# Type 8 LSAs originated by this router, with prefix and link-local

If a Type 8 is missing, the local link does not advertise its prefixes to the directly-connected neighbours. The remote router on the same link does not see the link’s prefixes.

The fix is usually to bounce the OSPFv3 process:

vtysh -c 'clear ipv6 ospf6 process'

The process restart regenerates all self-originated LSAs including the Type 8 and Type 9.

flowchart TB
  subgraph "Expected"
    E1["Type 1 Router-LSA<br/>R1 connected to link X"]
    E8["Type 8 Link-LSA<br/>link X carries 2001:db8:1::/64"]
    E9["Type 9 Intra-Area-Prefix-LSA<br/>2001:db8:1::/64 belongs to Type 1"]
  end
  subgraph "Inconsistency (missing Type 9)"
    M1["Type 1 Router-LSA<br/>R1 connected to link X"]
    M8["Type 8 Link-LSA<br/>link X carries 2001:db8:1::/64"]
    M9["(missing Type 9)<br/>R2 cannot install the prefix"]
  end

Failure mode 4 — IPv6 routing table divergence

The OSPFv3 RIB (show ipv6 route ospf6) is populated from the OSPFv3 LSDB. If the LSDB has the prefix but the RIB does not, the forwarding is broken.

The diagnostic sequence:

# 1. Verify the prefix is in the LSDB
show ipv6 ospf6 database intra-prefix
# (Type 9 LSAs visible)

# 2. Verify the Type 9 references the Type 1
show ipv6 ospf6 database intra-prefix verbose
# Referenced LS-type: Router
# Referenced LS-ID: <interface-id>
# Referenced Router: <router-id>

# 3. Verify the Type 1 has the referenced link
show ipv6 ospf6 database router verbose
# Router-LSA contents

# 4. Verify the RIB has the prefix
show ipv6 route 2001:db8:1::/64
# (empty if forwarding is broken)

# 5. Check the IPv6 RIB for OSPFv3 routes
show ipv6 route ospf6
# (empty if forwarding is broken)

If the LSDB has the prefix but the RIB does not, the most likely causes:

• R-bit clear. The Type 1 or Type 3 has R-bit clear; the downstream router’s SPF does not install.
• Forward-address unreachable. For Type 5 (external) routes, the forward-address is unreachable from the receiving router.
• Area mismatch. The router is in a different area and the Type 3 Summary does not propagate.
• Stub area configuration. The router is in a stub area and the Type 5 (external) is filtered.

Failure mode 5 — Authentication mismatch

OSPFv3 authentication (RFC 7166 trailer or IPsec) misconfiguration shows up as neighbour stuck in Init. The Hello packets are silently dropped on the receiver because the authentication check fails.

The diagnostic:

show configuration commands | match ospfv3.*authentication
# Compare SPI, algorithm, key on both sides

# Test with debug
debug ospf6 adj
# log shows: "Authentication failed for packet from fe80::1"

The fix is to align the SPI, algorithm, and key on both sides.

Diagnostic playbook

The OSPFv3 diagnostic sequence:

1. Confirm the scope. One adjacency, one area, or the whole domain? show ipv6 ospf6 neighbor shows the adjacency state; show ipv6 ospf6 shows the area state.
2. Verify the link-local. show ipv6 ospf6 interface eth0 shows the link-local; ip -6 addr show eth0 shows the interface’s link-local. They must match.
3. Verify the IPv6 firewall. show firewall ipv6 name ... rule ... shows the rule set; OSPFv3 must be permitted.
4. Verify the area and instance-id. show ipv6 ospf6 interface shows the area and instance-id; both sides must match.
5. Verify the LSDB. show ipv6 ospf6 database shows the Type 1, Type 8, Type 9 for the local topology. Missing LSAs indicate a process-level issue.
6. Verify the RIB. show ipv6 route ospf6 shows the OSPFv3 routes. Missing routes indicate a forwarding-plane issue.
7. Enable debug. debug ospf6 adj and debug ospf6 lsa show the protocol-level decisions. Apply sparingly.

Production failure modes

• Single firewall rule for OSPF. The operator writes one firewall rule for OSPF (protocol 89) on IPv4 and forgets the IPv6 rule. OSPFv3 control packets are dropped.
• Link-local change after interface bounce. The interface bounces and the link-local changes. The neighbour has the old link-local cached; the adjacency fails. The fix is to bounce both sides or to set the link-local explicitly with EUI-64 disabled.
• Area mismatch after a refactor. The operator moves an interface to a new area but forgets one side. The adjacency fails. The fix is to align both sides.
• Instance-id mismatch. The operator sets instance-id 1 on one side for testing and forgets to remove it. The adjacency fails. The fix is to remove the instance-id.
• R-bit clear due to passive interface. The operator marks the egress interface passive (no forwarding). The R-bit is cleared; downstream routers do not install the prefix.
• Type 9 missing after process restart. The OSPFv3 process restarts but the Type 9 is not regenerated. The LSDB has the Type 1 and Type 8 but no Type 9. The fix is to bounce the process again or to add the IPv6 prefix to the interface explicitly.

Rollback

The OSPFv3 rollback path:

# Capture the running configuration
show configuration commands | save /tmp/ospfv3-troubleshoot-$(date +%s).txt

# Compare
compare

# Commit with a short confirm window
commit-confirm 5

# Rollback if needed
rollback 1
commit

For a process-level fix:

# Bounce the OSPFv3 process
vtysh -c 'clear ipv6 ospf6 process'

# If the bounce does not resolve, restart FRR
sudo systemctl restart frr

The process bounce tears down every OSPFv3 adjacency and refloods every Type 1, Type 8, Type 9 LSA. Plan a maintenance window.

Production discipline

Cross-course references

The OSPFv3 concept lesson vyos-xxi-01-ospfv3-concept covers the protocol-level changes this lesson assumes. The OSPFv3 configuration lesson vyos-xxi-02-ospfv3-config covers the configuration tree. The OSPFv3 vs OSPFv2 lesson vyos-xxi-03-ospfv3-vs-ospfv2 covers the side-by-side comparison. The IPv6 lessons vyos-xi-06-ipv6-troubleshoot and vyos-xi-04-dhcpv6 cover the IPv6 primitives this lesson builds on. The OSPF troubleshooting part (vyos-xxii-01-neighbour-stuck through vyos-xxii-06-missing-route) covers the shared OSPF failure modes; this lesson covers the OSPFv3-specific overlay.

Quiz