high riskservice affecting~90 min

Runbook: Perform Route Redistribution

1 · Prerequisites

Confirm every item is in place before any state change.

Redistribution concept — why redistribute, route-map filtering, metric preservation, seed metric
Redistributing static into BGP — route-map filtering, seed metric, community tags
Redistributing OSPF into BGP — what survives the boundary, the MED, and feedback prevention
Redistributing connected routes — physical interface routes, when to include, when to exclude
Redistributing kernel routes — what `redistribute kernel` really carries, and why it is rarely the right answer
Redistribution anti-patterns — bidirectional loops, missing tags, suboptimal paths
Route-map composition — match and set clauses, sequence ordering, implicit deny
Administrative distance — how a router prefers one source over another
commit-confirm — the rollback safety net for remote changes

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· The prefix set is written down as an explicit list of prefixes, with an owner for each, BEFORE anybody opens configure. "Redistribute the OSPF routes" is not a prefix set; it is a promise to advertise whatever OSPF happens to hold on the day, including everything added to it next quarter by somebody who has never read this ticket.
· The source table has been read and counted, not assumed: show ip route ospf, show ip route static, show ip route connected, show ip route kernel as applicable, plus show ip route summary for the totals. The difference between what is in there and what is on your list is exactly what an unfiltered redistribution would leak.
· The current export is captured for every affected session: show ip bgp neighbors PEER advertised-routes and its count, or show ip ospf database external self-originate. Without a before, the after is a number with nothing to compare it to.
· It is established whether any peer already redistributes back towards this router. Mutual redistribution without a tag is the canonical routing loop, and it is a property of the pair, not of either router — so this question cannot be answered from this router alone.
· The administrative distance collision has been thought through for every prefix on the list: which protocol currently wins in the FIB, and which one wins after the change. Connected 0, static 1, eBGP 20, OSPF 110, iBGP 200 — an OSPF external route at 110 beats an iBGP route at 200 for the same prefix, whatever the operator intended.
· The receiving side has an inbound guard. Your prefix-list bounds what you meant to send; the peer's maximum-prefix bounds what a mistake can actually do to them. Confirm it exists before you give a redistribution the chance to test it.
· Out-of-band console access confirmed. A redistribution that changes the best path to the management network can remove the session you are typing in, and it can do it several seconds after a commit that appeared to succeed.
· The change window is agreed with whoever consumes these advertisements — the upstream provider, the peer AS, the iBGP mesh. BGP propagates a mistake faster than a phone call travels, and a leak that reaches a transit provider is their incident as much as yours.
· The rollback owner and the abort condition are named before the commit: which prefix count, on which command, means undo rather than investigate.

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Restate the intent in one sentence naming the source protocol, the destination protocol, and the exact prefixes. If that sentence needs the word "everything", stop and go back to the prefix list — this is the decision point the whole runbook exists to protect.
2Capture the baseline off the router: show configuration commands | strip-private, show ip route summary, the per-source tables you are about to redistribute from, and show ip bgp neighbors PEER advertised-routes for every session that will be affected.
3Choose the narrower tool if it fits. A fixed set of prefixes that does not follow interface or protocol state is an explicit set protocols bgp address-family ipv4-unicast network 203.0.113.0/24, not a redistribution. Redistribution earns its risk only when you want the advertisement to track the source protocol's state.
4Build the prefix-list first, in the candidate, with an explicit deny at the end: set policy prefix-list REDIST-OUT rule 10 action permit, ... rule 10 prefix 203.0.113.0/24, and a final set policy prefix-list REDIST-OUT rule 100 action deny. Enumerate; never rely on a range that "should" cover it.
5Build the route-map that references it: set policy route-map REDIST-OUT rule 10 action permit, ... match ip address prefix-list REDIST-OUT, plus any set metric the design calls for. The route-map is the change. The redistribute line is only where you attach it.
6If there is any path by which these routes could come back — a peer that redistributes towards you, a second router in the same pair — stamp a tag on the way out and deny it on the way in: set policy route-map REDIST-OUT rule 10 set tag 400 here, and match tag 400 under a deny rule on the inbound redistribution at the other end. The tag is a contract, so both ends have to be changed and both ends have to be told.
7Add the redistribution statement in the SAME candidate, never in a separate commit: set protocols bgp address-family ipv4-unicast redistribute ospf route-map REDIST-OUT. VyOS applies a candidate atomically, so policy-then-redistribution in one commit has no window. Two commits has a window, and BGP will use it.
8Read the diff before committing: compare. Confirm the route-map is referenced by name and spelled identically in both places. A typo produces a dangling reference whose behaviour you do not want to characterise for the first time on a live peering session.
9Have the diff peer-reviewed by somebody who can see the prefix list and the intent side by side. This is the last cheap moment; after the commit the review happens at the far end of a BGP session.
10Apply with commit-confirm 5. The confirm timer is not ceremony here: the failure mode is a leak that is invisible from this router and obvious from the upstream, and five minutes is roughly how long it takes to look.
11Verify at the export, not in the configuration: show ip bgp neighbors PEER advertised-routes. Count the prefixes and compare against the list you wrote in step 1. The configuration says what you asked for; this says what is leaving.
12Verify the routes carry the attributes the design specified — the metric, the tag, the community — with show ip bgp PREFIX for a representative prefix from the list, and one prefix that should NOT be there.
13Verify the FIB did not change under you: show ip route summary against the baseline, and show ip route for any prefix where the administrative-distance collision was a risk. A redistribution that changes which protocol wins locally is a forwarding change wearing an advertisement change's clothes.
14Check the far side before you confirm. The peer, the upstream, or the other router of the pair sees what you actually sent; this router sees what it meant to send. Where a route server or looking glass is available, use it.
15confirm only after the far-side check. Then save. Until save, a reboot silently undoes the whole change and the router returns advertising the old set.
16Watch for a feedback loop for a full convergence interval rather than declaring success at the commit: show ip ospf database external self-originate should not list a prefix this router learned from BGP, and prefix counts should settle rather than oscillate.
17Record the prefix list, the route-map name, the tag value, and the before and after export counts in the change ticket. The next person to touch this route-map needs to know what it was allowed to advertise and why.

4 · Verification

Confirm the procedure actually fixed the problem.

✓show ip bgp neighbors PEER advertised-routes contains exactly the prefixes on the written list and nothing else. The count matters as much as the contents: a redistribution that leaks tends to leak a lot, and a wrong count is visible before a wrong prefix is.
✓A prefix that is deliberately excluded is confirmed absent, by name. Proving what you did not send is the half of the test that unfiltered redistributions pass.
✓show ip bgp PREFIX for a representative redistributed prefix shows the intended metric and tag or community, and an origin of incomplete — the signature of a redistributed route rather than one from a network statement.
✓show ip route summary totals match the baseline, or differ only by an amount you can explain per protocol.
✓For every prefix flagged as an administrative-distance risk, show ip route PREFIX shows the protocol the design intended to win, not merely a route that resolves.
✓show ip ospf database external self-originate does not contain a prefix this router originally learned from BGP. That is the loop, and it is visible in the LSDB before it is visible in anybody's traffic.
✓Prefix counts on the affected sessions are stable across at least two observations a convergence interval apart. A count that is still moving is not a result.
✓The far side agrees — the peer, the upstream, or the other member of the pair reports the same prefix set you believe you are advertising.
✓show configuration commands | match redistribute shows every redistribution statement on this router carrying a route-map. An unfiltered one anywhere in the output is a finding even if it is not the one you just added.
✓The change is saved, and a compare from configure is empty — no candidate left behind for the next operator to commit by accident.

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶Inside the commit-confirm window with a leak confirmed: do nothing and let the timer expire. It reverts on its own, and waiting is both faster and less error-prone than composing a delete under pressure.
↶After confirm, the narrow undo is removing the redistribution and leaving the policy in place: delete protocols bgp address-family ipv4-unicast redistribute ospf, compare, commit. The prefix-list and route-map are inert without a consumer, and keeping them makes the retry a one-line change.
↶The broader undo is rollback 1, compare, commit, save. Read the compare output first — if anybody else committed in between, rollback 1 takes their change with yours.
↶Withdrawal is not instantaneous and it is not silent. Removing a redistribution sends BGP withdrawals; a peer that installed the leaked prefixes has to converge away from them, and a downstream that started preferring your path takes a routing change in both directions. Roll back deliberately, then verify the withdrawal at the far side.
↶POINT OF NO RETURN: prefixes that reached a transit provider or an internet exchange have been seen. Withdrawing them does not remove them from route collectors, looking-glass history, or the peer's logs, and it does not undo whatever traffic followed them while they were live. Treat a leak beyond your own AS as an incident with a notification obligation, not as a configuration mistake you quietly fixed.
↶POINT OF NO RETURN: a tag or community contract is bilateral. Removing your side of a feedback-prevention tag while the peer still filters on it leaves the peer filtering nothing, and neither end sees a symptom until the loop forms. Coordinate the removal; never unilaterally retire a tag.
↶If the rollback does not restore the baseline export count, stop and escalate rather than committing further changes. Two half-applied policy changes are much harder to reason about than one wrong one.

6 · Escalation

When the runbook isn't enough, contact:

· Escalate immediately, and treat it as an incident, if prefixes you do not own or did not intend to advertise have reached an upstream provider or an exchange. Notification is part of the remediation, not an optional courtesy, and the provider can filter faster than you can withdraw.
· Escalate to network engineering before committing if the redistribution would change which protocol wins in the FIB for any prefix. That is a forwarding change and it belongs to whoever owns the routing design, not to whoever is holding the ticket.
· Escalate to the peer AS or the other router's owner before configuring any tag-based feedback prevention. The tag is a contract that only works if both ends implement it, and a tag stamped by one side alone is a false sense of safety.
· Escalate to the upstream provider if prefix counts on a session do not settle within a convergence interval. Oscillation usually means two speakers disagree about a route's origin, and that is a conversation, not a knob on this router.
· Escalate to the change owner rather than widening the prefix list mid-change when the redistribution does not carry a route somebody expected. A missing prefix is a design question; adding a wildcard to make it appear is how the next leak gets built.
· Escalate to security if a redistribution has exposed internal addressing — management subnets, peering transits, or infrastructure loopbacks — outside its intended boundary. The prefixes are reconnaissance whether or not anybody routed to them.

Redistribution is not a copy. It is a standing grant: from the moment you commit it, one protocol’s routing table decides what another protocol advertises, and it keeps deciding, without asking again, for as long as the statement exists.

That is why the interesting part of this procedure is not the redistribute line. It is the list of prefixes you write down before you touch the router, and the filter that pins the grant to that list. A redistribution with a route-map advertises what you enumerated. A redistribution without one advertises whatever the source protocol happens to hold — today, and after every future change made by somebody who has never seen your ticket.

The redistribution syntax moved in VyOS 1.4

The Part XXXIV lessons are written for VyOS 1.3, where BGP redistribution lives at set protocols bgp 64512 redistribute ospf. On 1.4 and 1.5 the AS number moves to set protocols bgp system-as 64512 and redistribution moves under the address family:

set protocols bgp address-family ipv4-unicast redistribute ospf route-map NAME

Two more differences are worth knowing before you paste anything from a 1.3-era note. BGP redistribution takes metric and route-map and nothing else — there is no metric-type on the BGP side, because metric type is an OSPF LSA property that BGP does not carry. And the route-map set community form is set community add VALUE or set community replace VALUE, not the older additive keyword.

OSPF redistribution keeps its familiar shape: set protocols ospf redistribute bgp metric 200 metric-type 2 route-map NAME.

When this runbook applies

A prefix set that must be advertised by one protocol and is learned by another, where the advertisement should track the source protocol’s state — a customer link that should be withdrawn when it goes down, a loopback set that follows the IGP.
Adding a source to an existing redistribution, which is the same change with a shorter diff and exactly the same blast radius.
Retro-fitting a route-map onto an unfiltered redistribution somebody else committed. That is remediation, and it is urgent.

When it does not

A fixed set of prefixes that does not depend on protocol state. Use set protocols bgp address-family ipv4-unicast network 203.0.113.0/24. It is explicit, it is auditable in one line, and it cannot grow on its own. Reach for redistribution only when you want the tracking.
Making a route appear that is missing. That is vyos-rb-troubleshoot-missing-route. Redistributing a source until the prefix shows up is how a leak gets built one plausible step at a time.
Changing an existing route policy. That is vyos-rb-modify-route-policy-safely, which is about not breaking the consumers a policy already has.

Blast radius

Wider than the router, and asymmetric: the mistake propagates far faster than the correction.

The immediate reach is every session that carries the affected address family. A leaked prefix crosses an eBGP session in seconds and can reach a transit provider before you have finished reading your own diff. Once there, withdrawal is possible and forgetting is not — route collectors and looking glasses keep what they saw.

There is a local reach too, and it surprises people because the change was supposed to be about advertisement. Redistributing into OSPF creates external routes at administrative distance 110, which beat iBGP at 200 for the same prefix. The router starts forwarding along a path nobody chose.

Step 1: write the prefix list down, on paper, first

This is the step with no command and the highest value.

If the sentence describing the change needs the word “everything”, the design is not finished. “Redistribute connected” is a promise to advertise every subnet on every interface, including the management interface that gets added next month and the peering transit that should never leave the estate. The Part XXXIV lessons make the call per interface type, and the answer for management, transit and peering subnets is always no.

Then read what is actually in the source, because it is rarely what people remember:

Read-only / Safethe source table, counted

show ip route ospf
show ip route static
show ip route connected
show ip route kernel
show ip route summary

show ip bgp neighbors 203.0.113.2 advertised-routes

The gap between that output and your written list is precisely what an unfiltered redistribution would put on the wire. Look at it before you decide the filter is a formality.

Step 2: one candidate, one commit

VyOS gives you a safety property that most network operating systems do not, and this is the change where it matters most: the candidate is applied atomically. Build the prefix-list, the route-map and the redistribution statement in one candidate and commit once, and there is no interval in which the redistribution exists without its filter.

Service impact possiblepolicy and redistribution in a single atomic change

configure

# 1. Enumerate. Explicit permits, explicit deny at the end.
set policy prefix-list REDIST-OUT rule 10 action permit
set policy prefix-list REDIST-OUT rule 10 prefix 203.0.113.0/24
set policy prefix-list REDIST-OUT rule 20 action permit
set policy prefix-list REDIST-OUT rule 20 prefix 198.51.100.0/24
set policy prefix-list REDIST-OUT rule 100 action deny

# 2. The route-map IS the change.
set policy route-map REDIST-OUT rule 10 action permit
set policy route-map REDIST-OUT rule 10 match ip address prefix-list REDIST-OUT
set policy route-map REDIST-OUT rule 10 set metric 100
set policy route-map REDIST-OUT rule 10 set tag 400

# 3. Attach it. Same candidate. Never a second commit.
set protocols bgp address-family ipv4-unicast redistribute ospf route-map REDIST-OUT

compare
commit-confirm 5

Step 3: the tag, if the routes can come back

Mutual redistribution — this router pushing OSPF into BGP while a peer pushes BGP into OSPF — is the textbook loop, and the router’s own view gives no warning. The remedy is a tag stamped on the way out and denied on the way in.

Configuration changethe inbound half, at the other end

set policy route-map REDIST-IN rule 10 action deny
set policy route-map REDIST-IN rule 10 match tag 400

set policy route-map REDIST-IN rule 20 action permit

set protocols ospf redistribute bgp metric 200 metric-type 2 route-map REDIST-IN

The important property of a tag is that it is a contract between two routers, so it is never a change to one of them. Both ends have to be configured, both ends have to be told the value, and neither end can retire it alone — dropping your stamp while the peer still filters on it leaves the peer filtering nothing, with no symptom until the loop forms.

Step 4: verify at the export, and at the far side

The configuration tells you what you asked for. Only the export tells you what is leaving.

Read-only / Safecounts first, then attributes, then the FIB

show ip bgp neighbors 203.0.113.2 advertised-routes

show ip bgp 203.0.113.0/24
show ip route 203.0.113.0/24
show ip route summary

show ip ospf database external self-originate

Count first. A redistribution that leaks rarely leaks one prefix, so a wrong count is visible well before a wrong prefix is. Then confirm the attributes on one prefix that should be there and the absence of one that should not — proving the exclusion is the half of the test an unfiltered redistribution would also pass.

show ip route summary against the baseline catches the local surprise: if a redistribution has created OSPF external routes that now beat iBGP in the FIB, the totals move, and the router is forwarding differently than it was five minutes ago.

Then look from somewhere else. This router reports what it intended to send. Only the peer, the upstream, or a looking glass reports what arrived. confirm after that check, not before it — and then save, because until you do, a reboot returns the router to the old advertisement set with no diff to show for it.

Common patterns

Symptom	Likely cause	Where to look
Upstream sees internal prefixes	Redistribution committed without its route-map, or committed first	`show ip bgp neighbors PEER advertised-routes`
Advertised count far above the written list	Prefix-list range too broad, or no final deny	`show configuration commands` for the prefix-list
An expected prefix is absent	Not in the source table at all, or filtered by the final deny	`show ip route SOURCE` before blaming the route-map
Router forwards by OSPF where iBGP was intended	External route at distance 110 beats iBGP at 200	`show ip route PREFIX`
Prefix counts oscillate and never settle	Feedback loop through a mutual redistribution	`show ip ospf database external self-originate`
Everything correct until the next reboot	Committed but never saved	`show configuration commit`
Peer still filters on a tag you removed	One end of a bilateral contract changed alone	Both routers, together
Advertisement set grew months later with no change	Source protocol grew; the filter was a range, not a list	The prefix-list, and the ticket that widened it

Why this matters

Almost every redistribution incident is the same incident. Somebody needed a prefix advertised, redistribute made it appear, and the filter was going to be added in a moment. The change worked. Nothing looked wrong from the router, because from the router nothing was wrong — the leak is only visible from the far side of a session, and nobody had a reason to look there.

That is why this runbook spends its effort in three places that are not the command. The written prefix list, because a redistribution is a standing grant and you cannot bound a grant you have not enumerated. The single atomic commit, because VyOS will let you close the gap entirely and the two-commit habit comes from devices that could not. And the verification at the export and the far side, because the configuration cannot tell you what left the router.

The last of those is the one worth defending hardest. A wrong redistribution passes every check performed on the router that made it. It reads correctly, commits cleanly, and produces a routing table that looks fine. The evidence that it is wrong exists somewhere else, held by somebody else, and by the time they tell you, the prefixes have been seen by systems that do not forget.