Runbook: Troubleshoot OSPF Adjacency

An OSPF adjacency does not simply fail. It stalls at a specific state, and the state names the layer that failed. Reading it — from both ends — is most of this runbook, because the state determines which of five completely different investigations you are about to run.

State	What has already succeeded	What to look at
No neighbour listed	Nothing	Hello matching: area, timers, network type, authentication, passive, subnet
Init	Our Hellos reach them	One-way path, or they discard ours: capture from both ends
2-Way, both routers DROther	Everything that should	Nothing. This is the DR design working
ExStart	Hellos matched	Interface MTU first, then duplicate router-id
Exchange or Loading	The database exchange began	Delivery: loss, errors, a lossy or one-way link
Full, then down, repeatedly	All of it, intermittently	Duplicate router-id, dead-interval expiry, a flapping link

The single most common mistake in OSPF diagnosis is reading the state from one router. Nearly every field this runbook checks is a matching requirement between two routers, and a matching requirement is not observable from one side.

When this runbook applies

An adjacency that has never reached Full.
An adjacency that reached Full and dropped.
An adjacency that will not stay at Full.
A new router whose neighbours never appear.
An adjacency that fails after an MTU, area, authentication or addressing change.

When it does not

Two DROther routers sitting at 2-Way on a broadcast segment. That is correct. On a multi-access segment the DR and the BDR describe the topology; every other router holds a Full adjacency with those two and stays at 2-Way with its DROther peers. Treating it as a fault leads to changing priorities on a working segment.
A Full adjacency that is not delivering the route you want. The adjacency is doing its job. Whether an LSA was originated, whether it survived an area boundary, and whether the route was selected and installed are separate questions with separate evidence — that is the missing-route runbook.
A router that has no OSPF configuration on the interface at all. That is a build request, not an incident, and adding OSPF to an interface during a page has a blast radius nobody has assessed.

Blast radius

Every diagnostic step below is read-only, which makes the ordering free: there is no reason to skip a cheap check to save time. The risk in an OSPF incident is concentrated in three actions, and all three are readily available.

The second is mtu-ignore, discussed below. The third is any change to an area — its identifier, its type, its summarisation — which is an area-wide event that will disturb adjacencies that are currently healthy.

Step 0: name the adjacency, and get the far end

Which router, which interface, which neighbour router-id, which area. Then arrange access to the other end, or get its owner on the call.

That second half is not process for its own sake. Area identifier, area type, hello interval, dead interval, network type, authentication and MTU are all requirements that two routers must agree on. Every one of them is invisible from one side. Working a matching problem single-ended is how an operator spends an afternoon confirming that their own configuration is correct — which it may well be.

Step 1: read the state from both ends

Read-only / Saferun this on each router, and compare

show ip ospf neighbor
show ip ospf neighbor detail
show ip ospf interface
show ip ospf

The pair of answers is more informative than either one. A router that sees the peer in Init while the peer sees no neighbour at all is a one-way path — our Hellos are arriving there, theirs are not arriving here — and no single-ended view shows that.

show ip ospf interface is the one to read carefully. It carries the area, the network type, the timers, the MTU, the cost and the interface’s own state and role, which is the whole Hello matching list in one place. show ip ospf carries the router-id, which is the identity the rest of the area holds.

Step 2: no neighbour at all — the Hello matching list

Every field below must agree between the two ends. Every disagreement causes the Hello to be discarded, and every discard is silent: no error, no log line an operator would notice, nothing but an empty neighbour list.

Field	Read it with	Failure signature
Area identifier	`show ip ospf interface`	Empty neighbour list on both ends
Area type (stub, NSSA, standard)	`show configuration commands \| match ospf`	Empty neighbour list; the type is carried in the Hello options
Hello and dead intervals	`show ip ospf interface`	Empty neighbour list, both sides look correct in isolation
Network type	`show ip ospf interface`	Empty neighbour list; broadcast and point-to-point do not interoperate
Authentication type, key identifier, key	`show configuration commands \| match authentication`	Empty neighbour list; the packet is dropped after being received
Passive	`show ip ospf interface`	No Hellos sent at all on that interface
Subnet and mask	`show interfaces`	Two routers on the same wire in different subnets never see each other

Two of these deserve naming because they are the ones that produce the most confident wrong answers.

Passive on both ends. A passive interface participates in OSPF — its subnet is advertised — but sends no Hellos. Marked passive at both ends, both routers are listening and neither is speaking. The evidence is an empty neighbour list on two routers whose configuration each look entirely reasonable.

Authentication. The type, the key identifier and the key itself must all agree. A mismatch is dropped after the packet has been received, so the interface counters show traffic and the neighbour list stays empty. VyOS configures this per interface, for example set protocols ospf interface eth0 authentication md5 key-id 1 md5-key SHAREDSECRET, with a per-area form available for an area-wide policy. Where a key chain is in use, the lifetime windows and the routers’ clocks matter as much as the key: an expired acceptance window and a wrong key look identical from the neighbour list.

Before concluding the far end is misconfigured, prove the Hellos are arriving.

Read-only / Safeare the packets even there — run on both ends

monitor traffic interface eth0 filter 'proto ospf'

That separates “the peer is not sending” from “the peer is sending and we are discarding”, which have entirely different owners.

Step 3: ExStart — check MTU before anything else

The database description packet carries the sending interface’s MTU. A router that receives a packet claiming an MTU larger than its own interface MTU discards it, so the master and slave negotiation never completes and the adjacency sits in ExStart.

Read-only / Safethe same command on both routers; compare the MTU line

show ip ospf interface eth0
show ip ospf neighbor detail

This is the dominant ExStart cause by a wide margin, which makes it the cheapest first check rather than merely a likely one. There are two fixes and they are not equivalent.

Aligning the MTU on both sides is the real fix, and it is the right answer whenever both ends are under one owner. It bounces the interface, so it is a short service event rather than a free one.

`mtu-ignore` is not a licence to ignore MTU

set protocols ospf interface eth0 mtu-ignore makes OSPF skip the MTU check during the database exchange. It does not change the interface MTU, and it does not change what the data plane does with a packet that is too large.

There is a legitimate use: a link whose lower MTU is deliberate and cannot be changed — a provider tunnel with a fixed MTU on one side and Ethernet on the other — where the operator has separately established that nothing needs to send larger frames across it.

Used instead of that analysis, it converts a loud failure into a quiet one. The adjacency comes up, the ticket closes, and the MTU disagreement is still there waiting for the first large flow. Whoever meets it next will be debugging intermittent stalls on a link whose OSPF looks perfect.

If you use it, record why in the ticket, name the owner of the underlying mismatch, and give the follow-up a date.

If the MTU agrees and the state is still ExStart, read the router-ids. Two routers holding the same one cannot complete the negotiation, because each believes the other is itself.

Step 4: Exchange or Loading — stop reading configuration

Both of these states mean the matching requirements are already satisfied: the Hellos agreed, the negotiation completed, and the two routers began exchanging database information. What is failing is delivery.

Read-only / Safethe link, not the protocol

show interfaces ethernet eth0
show ip ospf neighbor detail
show ip ospf database

Read the interface error and drop counters, and read them as a rate rather than a total — a counter that has been climbing since the last reboot says much less than one climbing now. A neighbour in Loading with a growing queue of requested LSAs is the signature of update packets being lost in transit, which is congestion or a lossy path, not a configuration fault.

Continuing to edit OSPF configuration at this point is the classic wasted hour. The protocol is working; the link is not.

Step 5: Full, and it will not stay there

A flapping adjacency has three common causes, and they are separable with cheap evidence.

A duplicate router-id. Two routers holding the same identity originate router LSAs that the database cannot tell apart. The database oscillates, the adjacency flaps, and FRR logs the duplicate. This is the highest-impact of the three, because it corrupts the area’s view of the topology rather than merely interrupting one link.

Read-only / Safeidentity, then the database, then the log

show ip ospf
show ip ospf database self-originate

Read-only / Safethe daemon's own complaint

sudo journalctl -u frr | grep -i duplicate

Dead-interval expiry. Hellos are being sent and are not arriving within the dead interval — packet loss on the link, or a router too busy to service the protocol. The interface counters and the router’s CPU state separate these from each other.

A flapping link. The physical path is going up and down and OSPF is faithfully reporting it. The interface counters and the system log carry the link events; the adjacency is a symptom, not the fault.

Why the router-id is established at process start, and what that costs

The router-id identifies this router in every router LSA it originates. Other routers hold it in their databases and build the shortest-path tree from it, so it cannot be changed underneath a running process without invalidating everything already flooded.

The consequence is a step operators routinely miss: committing a new router-id changes the configuration and does not change the running process. The router keeps advertising its old identity, the fault persists, and the configuration now disagrees with reality — which is worse than before, because the next person reads the configuration and believes it.

Applying it needs the OSPF process restarted, and that restart is not scoped to the adjacency you were fixing. Every adjacency on the router drops, every router LSA is re-flooded under the new identity, and every router in the area recomputes.

There is a second consequence worth holding on to. When no router-id is configured, FRR derives one from the addressing — the highest loopback address, or the highest interface address if there is no loopback. That is convenient and unstable: adding a loopback with a higher address changes the router’s identity at the next process start, and the estate discovers it as an unexplained reconvergence weeks after the change that caused it. Configuring the router-id explicitly on every router is the whole prevention.

Step 6: debug, narrowly and with an end

The OSPF debug commands print every packet with its fields parsed, which is exactly what an authentication or database-description fault needs and is also a great deal of log volume. A single adjacency forming can produce hundreds of lines, and the daemon is writing them while it is also running the protocol.

Enable it on the affected router only, after the cheaper evidence is exhausted, with the disable command already decided. A debug left running is a fault that surfaces weeks later as unexplained CPU and a full log partition, and by then nobody connects it to this incident.

What each step costs if you get it wrong

Action	Cost when it is the wrong move
Diagnosing a matching requirement from one end	An afternoon confirming your own configuration is correct
Treating 2-Way between DROthers as a fault	Priority changes on a working segment, and a new fault
Reaching for `clear ip ospf process`	Every adjacency on the router drops, and the evidence is gone
Setting `mtu-ignore` instead of comparing MTU	A quiet MTU mismatch the data plane still pays for
Changing an area to fix one link	An area-wide event that disturbs adjacencies that were healthy
Committing a router-id without restarting the process	Configuration and running state disagree, and the fault persists
Leaving OSPF debug enabled	CPU and log growth that surfaces long after anyone remembers why
Declaring victory at Full	A synchronised adjacency delivering none of the routes the ticket was about

Escalation, and the option to hold

Escalate the moment the evidence crosses a boundary you do not own, and send the evidence rather than the conclusion. A capture showing the peer’s Hellos carrying a different area or a different interval is complete proof and makes the handover a two-minute conversation. A capture showing your Hellos leaving and nothing arriving is complete proof that the fault is in the path, and no configuration change on either router will address it.

Hold rather than improvise when the only available action suppresses evidence instead of resolving a fault. Clearing the process to “reset” a flap, enabling mtu-ignore to make ExStart go away, restarting a router because the ticket is old: each removes today’s symptom and moves the fault to a moment nobody is watching. Record the hold with an owner and an end time, and state what stays broken while it holds — including which prefixes are unreachable, because that is the number the person deciding actually needs.

Why this matters

OSPF is unusually kind to a disciplined operator and unusually cruel to a hurried one. It is kind because the failure announces its own layer: the neighbour state tells you whether the Hellos matched, whether the exchange started, and whether delivery is working, before you have formed a single hypothesis. Almost no other protocol hands over that much for one command.

It is cruel because every mismatch is silent. An area identifier that disagrees, a hello interval that disagrees, an authentication key that disagrees — all of them produce exactly the same evidence, which is no evidence: an empty neighbour list on two routers whose configuration each look fine to the person who wrote them. That symmetry is why the discipline that matters most is the least technical one in this runbook: get the other end before you start.

And the reset is always available. Clearing the process brings the adjacency back often enough to feel like a fix, and it takes the evidence with it every time. An estate can be recognised by how often that command appears in its tickets, and by how many of those tickets were closed without a cause.

1 · Prerequisites

2 · Pre-checks

3 · Procedure

4 · Verification

5 · Rollback

6 · Escalation