Runbook: Add a Static Route

A static route is not added to the routing table. It competes for it, and at the default administrative distance of 1 it beats every dynamic source in the table except a connected route. Whatever OSPF or BGP has to say about the prefix stops mattering on this router the moment you commit.

That is usually the point. What makes it a production change rather than a one-liner is the other half of the same property: a static route has no mechanism for noticing that it has become wrong. A dynamic route withdraws when the path behind it fails. A static route does not. It keeps pointing at the same next-hop through the outage, the maintenance, the re-addressing project and the decommission, because nothing in the router’s model of the world can tell it otherwise.

So this runbook front-loads two questions that take about a minute each and prevent most of the ways this goes wrong: what carries this prefix today, and does the next-hop actually resolve.

When to use this runbook

• A prefix has to be reachable from this router and no dynamic protocol carries it here.
• A floating backup path is being installed behind a dynamic primary.
• Traffic for a specific destination is being pinned during a migration, with an end date recorded in the ticket.

When not to use it

• To work around a dynamic protocol that is not converging. A distance-1 static will make the symptom disappear, which is exactly the problem: the cause stays, the static outlives the incident, and the next person finds a routing table that contradicts the design with no record of why.
• For the default route. Same tree, same syntax, entirely different blast radius — the default route is every destination the router does not otherwise know, and it deserves its own change.
• For blackhole or reject routes. Same configuration tree, opposite intent, and the verification is inverted: success is traffic not arriving.
• For source-based decisions. A static route matches on destination only. Choosing a path by source, by port or by mark is policy-based routing.

Blast radius

Locally: every packet this router forwards toward the prefix, for as long as the route exists.

Beyond this router: it depends entirely on whether the estate redistributes statics. redistribute static in an IGP or in BGP turns a local operational fix into an advertisement, and the routers that accept it will forward toward this one on the strength of it. Read the redistribution policy, not just the redistribute statement — a prefix-list and a route-map usually decide which statics actually leave, and “my prefix is not in the list” is a fact to verify rather than assume.

Inputs

• The prefix, in the exact form it will be written.
• The next-hop, and whether it sits on a connected subnet of this router.
• The form: next-hop with interface, next-hop alone, or interface alone.
• The distance, decided in advance: 1 or 210.
• A description carrying the change reference and the reason.
• Whether the estate redistributes static routes.
• The owner of the far end, for the return path.

Step 1: Find out what carries the prefix today

show ip route 10.20.0.0/16
show ip route 192.0.2.99
show configuration commands | match redistribute

Three answers to the first command, and each one changes the change:

• Nothing carries it. The static is additive here, and the rollback restores nothing. That sounds safe and is worth thinking about: after a rollback, traffic for the prefix falls to the default route and leaves the building instead of failing locally, which is harder to notice.
• Something carries it at a higher distance. Your static will win. Confirm that displacing it is the intent, in the ticket, with the person who owns the dynamic path.
• Something carries a more specific prefix. This is the one that catches people out.

Step 2: Confirm the next-hop resolves

An indirect static route — a next-hop with no interface — does not carry its own egress. The kernel performs a second lookup on the next-hop address, finds a route that reaches it, and uses that route’s interface. If that lookup fails, the route is installed inactive and never enters the FIB.

The show ip route output for the next-hop is what tells you which form to use:

• The next-hop is on a connected subnet of this router: use the direct form, next-hop plus interface. The interface is explicit and the route stops depending on another route staying correct.
• The next-hop is reachable through another route: the indirect form is appropriate, and you accept that this route’s health is now tied to that other route’s.
• The next-hop does not resolve at all: stop. This is not a route you can add yet.

Step 3: Choose the distance before you type it

Distance 1 is a primary: it wins against everything except connected routes. Distance 210 is a floating backup: it sits behind eBGP at 20, OSPF at 110, IS-IS at 115 and iBGP at 200, stays inactive while any of them carries the prefix, and becomes active the moment they withdraw.

The failure mode is quiet in both directions. A backup committed at distance 1 is permanently active and the intended primary is permanently ignored — and everything works, so nobody finds out until the day the static path is the one that breaks. A primary committed at 210 is permanently inactive, and traffic keeps using a path somebody had decided to move off.

And two statics for the same prefix at the same distance are not a primary and a backup at all: they are equal-cost candidates, and the router load-shares between them. If you want a backup, the distances must differ.

Step 4: Commit, with a description

configure
set protocols static route 10.20.0.0/16 next-hop 192.0.2.99 interface eth0
set protocols static route 10.20.0.0/16 description 'CR-1231 dc01-eu transit, review 2026-11-01'
compare
commit-confirm 10
exit

The description is not exported to FRR. It lives in the VyOS configuration tree and appears in show configuration protocols static, which is precisely where the next operator will be looking when they find a route nobody remembers. A change reference, the destination in words, and a review date cost one line and are the only documentation that reliably survives.

Read the compare output for the next-hop especially. A transposed octet produces a route that commits cleanly, installs cleanly, and forwards into nothing — there is no validation step anywhere in the stack that knows what you meant.

Point of no return. After the commit this router’s forwarding decision for the prefix has changed, and if the route is redistributed, so has every downstream router’s.

Step 5: Cross-check three views

vyos@vyos:~$ show ip route 10.20.0.0/16

S>* 10.20.0.0/16 [1/0] via 192.0.2.99, eth0, 00:00:07

S on its own means FRR has the route and has not selected it. The word inactive means the recursive lookup for the next-hop failed. Neither forwards a packet.

Then confirm the kernel agrees:

show configuration protocols static
show ip route static
ip route show

Three views of one route, and they answer different questions. show configuration protocols static is what you typed. show ip route static is what FRR accepted into its RIB. ip route show is the kernel FIB — the only one of the three that forwards a packet, where the entry should carry proto static.

Step 6: Test both directions, from a real source

traceroute 10.20.0.5
traceroute -s 192.0.2.1 10.20.0.5

The first traceroute leaves with whichever source address the router chooses for itself. That is often not the address production traffic carries, and on a router with several interfaces or a bound management path it can take a different route entirely. The second form pins the source, which is the test that matches reality.

Then test the return path from the far end, or have its owner do it. A static route is one-directional: it tells this router how to reach the destination and says nothing about how the destination reaches back. Forward success with return failure is the commonest way this change appears to have failed when it has in fact half succeeded, and the remaining half is somebody else’s routing table.

Asymmetry is not automatically a fault — return paths differ from forward paths all over the internet. It becomes a fault when something stateful sits in the path and only sees one direction of the conversation, which on a routed estate with firewalls is most of the time.

Only when both directions are proven:

configure
confirm
save
exit

Rollback

configure
delete protocols static route 10.20.0.0/16
compare
commit
save

The rollback restores the baseline, and the baseline is the thing to have written down. Removing the route does not return the prefix to a neutral state; it returns it to whatever show ip route 10.20.0.0/16 answered before the change. If that was a default route, traffic still leaves the router — just not where anyone intends, and it fails somewhere downstream where nobody connects the failure to this change.

There is a middle state worth knowing about. set protocols static route 10.20.0.0/16 disable keeps the route in the configuration but stops it being rendered to FRR, so forwarding reverts while the intent stays visible and reviewable. For a change that is contested rather than wrong, that is a better place to stop than deletion.

If the route was redistributed, deletion withdraws it from every router that accepted the advertisement. That convergence takes time and is worth watching rather than assuming.

Common patterns

Escalation

Escalate rather than commit when:

• The prefix is already carried by OSPF or BGP. Overriding a dynamic protocol with a static is a design decision with a long tail, not a routing fix.
• The next-hop does not resolve and on-link is being suggested as the way through.
• The forward path works and the return path does not. Adding a second route on this router will not fix somebody else’s table.
• The router redistributes static routes into BGP. A local fix becoming an external advertisement is a different conversation with a different set of people in it.

Holding is a real option: commit the route with disable, name the owner of the blocker, agree an end time, and leave the forwarding table exactly as you found it.