Runbook: Configure an OSPF Neighbour

Adding an OSPF neighbour is not really a link change. The adjacency is the visible part; the change is to the link-state database, and the link-state database is shared. The moment the new peer reaches Full, this router floods its Type-1 LSAs to a topology that has not seen them before, imports that topology’s LSAs, and every router in the area re-runs SPF. Traffic can move before you have tested anything.

That is why the two decisions that matter in this runbook both happen before the commit: what the link’s cost will be, and which interfaces the network statement is going to match. Everything after the commit is verification.

When this runbook applies

• A new physical or logical link is being added between two routers that are already in the same OSPF domain.
• An existing link is being brought into OSPF for the first time.
• An interface is moving from passive to active because a second OSPF speaker has appeared on that segment.

When it does not apply

• An adjacency that used to work and stopped. That is a diagnosis, not a change. Use the OSPF adjacency troubleshooting runbook; do not start editing configuration on a router whose LSDB you have not read.
• Enabling OSPF on a router that has never run it. That change also decides where the default route comes from and which interfaces are passive by default. It is a build, not a link addition.
• Changing the router-id. The router-id is the OSPF identity: it is the Advertising Router on every LSA this router originates and the tie-break in DR election on every multi-access segment it touches. Changing it requires an OSPF process restart, which tears down every adjacency on the box. Separate ticket, separate window.
• An adjacency over a tunnel (WireGuard, GRE, IPsec VTI). The shape is the same but the network type must be point-to-point and the MTU question is not optional. Read vyos-xix-02-ospf-interface-config first.

Blast radius

One adjacency, one area, and every prefix whose best path this router currently advertises or receives.

The number to write on the ticket is not “one link”. It is the count of prefixes in show ip route ospf before the change, because that is the set that can move. On a router with two upstream paths and a default learned by OSPF, adding a third adjacency can silently make the new link the preferred path for all of them.

The fields that must match

Every one of these has to agree at both ends of the link, and all but one of them fail identically when they do not: no adjacency, no log line, an empty neighbour list. The area, network type, timers and authentication are compared from the Hello packet itself; the MTU is compared later, during the database exchange, which is why it fails differently. Agree all of them with the far end in writing before anyone types set.

The MTU case is the one that is diagnosable at a glance, because it is the only mismatch that produces a neighbour entry rather than silence: the two ends exchange Hellos, agree to build an adjacency, and then fail the Database Description negotiation. ExStart after 60 seconds means MTU until proven otherwise.

Prove the way back in

# On the console / serial / IPMI path, not over the link you are about to change:
show version
show interfaces

An out-of-band path that exists on a wiring diagram is not an out-of-band path. Log into it, get a prompt, and leave the session open until the change is confirmed. This costs a minute and is the difference between a rollback and a site visit.

Capture the baseline you will diff against

show configuration commands | grep ospf
show ip ospf
show ip ospf neighbor
show ip ospf interface
show ip route ospf

Save the output somewhere that is not this router. A baseline stored on the box you are about to change is a baseline you may not be able to read when you need it.

show ip route ospf is the one that matters most and the one people skip. It is the only artefact that lets you answer, twenty minutes later, the question the change ticket will actually be judged on: did anything move that was not supposed to move?

Decide the cost, then look at what it competes with

Read the pre-change show ip route ospf and find the prefixes this router reaches over OSPF today. For each, note the cost. The new link will win any prefix where its cost is lower, and will share any prefix where its cost is equal.

If the new link is intended as a backup, its cost must be higher than the primary’s — deliberately higher, by a margin you chose, not by whatever auto-cost happens to produce.

Build the candidate, parameters first

Order matters here for a reason that is easy to miss: the per-interface block is inert until the network statement matches the interface. Set the parameters first and the interface joins OSPF already configured correctly. Set the network statement first and the interface joins with defaults, sends Hellos with the wrong timers, and — if the far end is already up — forms nothing while you are still typing.

configure

# 1. Per-interface parameters, while eth1 is still outside OSPF
set protocols ospf interface eth1 network-type point-to-point
set protocols ospf interface eth1 hello-interval 10
set protocols ospf interface eth1 dead-interval 40
set protocols ospf interface eth1 cost 20
set protocols ospf interface eth1 authentication md5 key-id 1 md5-key SHARED-KEY-HERE

# 2. The line that starts Hello packets
set protocols ospf area 0 network 10.0.0.0/30

On authentication: MD5 is the form shown here because it is the one the course’s authentication lesson configures directly on the interface. If your estate standard is HMAC-SHA-256, the key chain has to exist on both routers and be in its send lifetime before either interface references it — read vyos-xix-05-ospf-authentication and treat the key distribution as its own step, over a channel that is not the link you are building.

Adding authentication to an interface that already carries a working adjacency drops that adjacency the moment one side commits. That is expected, it is not a fault, and it is why both ends belong in the same window.

Read the diff before you commit

compare

Read it against the agreed must-match fields, one line at a time, and have the peer reviewer read the same output. This is the last point where a typo costs nothing. After the commit, a wrong hello-interval is indistinguishable from a cable in the wrong port: both present as an empty neighbour list.

VyOS helps here in a way worth naming. A configuration path that does not exist is rejected at the set, not at the commit — so a command that is wrong for your image fails before any state changes. A command that is valid but wrong for your intent commits happily. compare is the only defence against the second kind.

Commit behind a timer

commit-confirm 10
exit

Point of no return, with a leash. From here the adjacency can form and traffic can move. The ten-minute timer is what makes it reversible: if you do nothing, the router restores the previous configuration by itself.

Leave configure mode. Verification runs from the operational shell, and an operator sitting in configure mode is an operator who is one absent confirm away from an unplanned rollback in the middle of a test.

Watch the adjacency, then the routing table

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

In that order, because each answers a different question:

1. Did it come up? Full within a dead interval. Init or 2-Way means the Hellos disagree. ExStart or Exchange means MTU.
2. Did it come up the way we agreed? neighbor detail carries the timers, the network type and the interface MTU each side is using.
3. Did anything else join? show ip ospf interface is where an over-broad network statement becomes visible. Count the interfaces and compare against the ones you named.
4. Did anything move? Diff against the baseline capture.

An adjacency that reaches Full and then flaps back is not a slow adjacency. It is usually a duplicate router-id or an MTU mismatch that only bites during the first full database exchange; check journalctl -u frr before re-committing anything.

Confirm, or hold

configure
confirm
save
exit

confirm cancels the timer. save writes the active configuration to disk — without it, the next reboot silently reverts everything you just did.

Holding is a first-class outcome. If the adjacency is up but the route diff shows something you did not expect, you do not have to decide under time pressure. Let the timer run out. The cost is one change window; the cost of confirming a topology change you do not understand is measured in whatever traffic took the new path. The change owner makes that call, and makes it before T+8 on a 10-minute timer, so there is room to capture evidence first.

Rollback

The rollback is the timer, and the timer is only useful if you have not already confirmed. That is the whole argument for committing behind one.

configure
rollback 1
commit
save
exit

Two things about an OSPF rollback that catch people out:

• It is not instant. The adjacency persists until the dead interval expires — 40 seconds at the default. A show ip ospf neighbor run five seconds after the rollback commit will still show the peer, and that is not a failed rollback.
• It is not local. The peer holds this router’s LSAs until they are withdrawn or age out, and every router in the area re-runs SPF again on the way back. Check show ip route ospf on both ends before declaring the estate restored.

reset ip ospf process is not a rollback. It restarts the whole OSPF process on this router, tearing down every adjacency the router has and re-flooding every LSA it originated. It is a recovery tool for a router-id collision, used in a window, with the far ends warned.

Common patterns

Provenance

This runbook has not been executed end to end against a live pair of routers, which is why last_verified reads pending rather than carrying a date. Its command set is taken from the course’s own OSPF lessons — vyos-xix-01-ospf-basics, vyos-xix-02-ospf-interface-config and vyos-xix-05-ospf-authentication — and from the commit discipline in vyos-vi-02-commit-confirm and vyos-vi-06-remote-change-discipline. No output is reproduced here, because none of it was captured.