OSPF ECMP — equal-cost behaviour, default configuration, when ECMP applies

OSPF is a link-state protocol. The router computes the shortest-path tree (SPT) from itself to every destination; all equal-cost paths in the SPT are candidates for ECMP. The operator who enables maximum-paths and aligns the costs gets ECMP across the SPT paths.

This lesson is the operator’s reference for OSPF ECMP: the default behaviour, the maximum-paths configuration, the cost-equal requirement, the intra-area vs inter-area ECMP distinction, and the production failure modes that arise when the costs are not aligned.

OSPF’s default ECMP behaviour

By default, OSPF installs only the first equal-cost path in the routing table. If the SPT has two equal-cost paths to 10.0.0.0/24 (e.g., one via R-A with cost 20 and one via R-B with cost 20), OSPF picks one and discards the other.

The operator who wants ECMP must explicitly enable it:

set protocols ospf parameters maximum-paths 4
commit
save

The maximum-paths 4 configuration allows up to 4 equal-cost OSPF paths to be installed in the routing table. The default is 1; the maximum is typically 64 or 128 depending on the platform.

flowchart LR
  R1["R1 (OSPF ECMP)"]
  RA["R-A"]
  RB["R-B"]
  RC["R-C"]
  DEST["10.0.0.0/24"]
  R1 -- "cost 10" --> RA
  R1 -- "cost 10" --> RB
  R1 -- "cost 10" --> RC
  RA --> DEST
  RB --> DEST
  RC --> DEST
  R1 -- "ECMP (maximum-paths 4)" --> DEST

The cost-equal requirement

OSPF ECMP requires the total cost to the destination to be equal across paths. The total cost is the sum of the interface costs along the path.

The operator who wants ECMP must align the costs:

# Set the interface cost explicitly
set protocols ospf interface eth0 cost 10
set protocols ospf interface eth1 cost 10
commit

Or use the default reference bandwidth and adjust per-interface:

# Auto-cost based on reference bandwidth (default 100 Mbps)
# A 10G interface gets cost 10; a 1G interface gets cost 100
set protocols ospf auto-cost reference-bandwidth 10000
# (now 10G = 10, 1G = 100)

Intra-area ECMP

Intra-area ECMP is the simplest case. The destination is in the same area as the router; the SPT has equal-cost paths to the destination; the operator enables maximum-paths.

vyos@r1:~$ show ip ospf database router

                Router Link States (Area 0)
LS age: 100
Options: 0x2 : *|--|-|-|--|0|--|--|--|
LS Type: Router-LSA
LS Id: 1.1.1.1
Advertising Router: 1.1.1.1
LS Seq Number: 80000001
...
Number of Links: 4

Link ID         Adv Router       Cost  Type
2.2.2.2         2.2.2.2          10    Point-to-point
3.3.3.3         3.3.3.3          10    Point-to-point

The Type-1 LSA has links to R2 and R3 with equal cost (10). The SPT computes two equal-cost paths to 10.0.0.0/24 (via R2 and R3); both are ECMP candidates.

Inter-area ECMP

Inter-area ECMP is more subtle. The destination is in another area; the router learns about it via Type-3 LSAs from the ABR.

The ABR generates one Type-3 LSA per destination prefix. If there are two ABRs advertising the same prefix with equal cost, the router has two Type-3 LSAs and two equal-cost paths.

flowchart LR
  subgraph "Area 0 (backbone)"
    ABR1["ABR-1"]
    ABR2["ABR-2"]
  end
  subgraph "Area 1"
    DEST["10.0.0.0/24"]
  end
  subgraph "Area 2"
    R1["R1 (OSPF ECMP)"]
  end
  ABR1 -- "Type-3 LSA<br/>cost 20" --> R1
  ABR2 -- "Type-3 LSA<br/>cost 20" --> R1
  DEST --> ABR1
  DEST --> ABR2

The router computes the SPT to both ABRs. If the costs are equal, both ABRs are ECMP candidates; the routing table has two next-hops (one via each ABR).

External-route ECMP (Type-5)

External routes (Type-5 LSAs) are advertised by ASBRs. The metric on the Type-5 LSA determines the cost; the operator who redistributes from another protocol must set the metric.

For ECMP across multiple ASBRs, the metrics must be equal:

set protocols ospf redistribute connected metric-type 1 metric 20
set protocols ospf redistribute static metric-type 1 metric 20
commit

With equal metrics, the router installs both ASBR paths as ECMP candidates.

AS-border router ECMP

ASBR ECMP is the same as ASBR-single-path but with multiple ASBRs advertising the same external prefix. The costs must be equal.

A common production pattern: two ASBRs, both redistributing the same external routes, with equal OSPF costs. The local area routers see two equal-cost paths to the external destination.

The maximum-paths knob in detail

The OSPF maximum-paths knob controls the maximum number of equal-cost paths installed:

# Allow up to 8 equal-cost OSPF paths
set protocols ospf parameters maximum-paths 8
commit

The default is 1; the maximum depends on the platform (typically 64 or 128).

The knob is global for OSPF; there is no per-area or per-interface setting.

Validation

# 1. The maximum-paths is configured
show configuration commands | match maximum-paths

# 2. The ECMP routes are in the routing table
show ip route 10.0.0.0/24
# Multiple next-hops should appear

# 3. The OSPF database has the routes
show ip ospf database

# 4. The interface costs are aligned
show ip ospf interface eth0
show ip ospf interface eth1
# Both should show the same cost

# 5. The ABRs advertise equal costs
show ip ospf border-routers

# 6. The traffic distribution
# Run iperf3 with many parallel streams and observe per-path utilisation
iperf3 -c 10.0.0.2 -P 10

A clean validation: maximum-paths is configured; the costs are aligned; the routing table has multiple next-hops; the traffic distributes.

Production failure modes

Only one path is installed despite equal costs

The operator configured maximum-paths and aligned the costs but show ip route shows one next-hop. Causes:

• maximum-paths not committed — verify with show configuration commands.
• Costs not actually equal — verify with show ip ospf interface. Auto-cost can produce unequal costs.
• Type-3 LSA from only one ABR — the destination has only one ABR advertising it; the other ABR does not have the prefix in its LSDB.

Inter-area ECMP fails because of cost mismatch

The destination is in a remote area; the router has two Type-3 LSAs from two ABRs but only one is installed. Cause: the costs differ.

Diagnostic: show ip ospf database summary shows the Type-3 LSAs with their metrics. If the metrics differ, the lower one wins; the higher one is not installed.

The fix: align the costs. The operator can adjust the interface cost on the link to each ABR.

ECMP across redistribution

The operator redistributes the same prefix from two sources (e.g., a static route and a BGP route). OSPF sees two Type-5 LSAs but only one is installed. Cause: the metrics differ.

Diagnostic: show ip ospf database external shows the Type-5 LSAs with their metrics. Align the metrics.

Path-flap during ECMP

A path flaps (the link goes up and down). The OSPF neighbour transitions through the states; the SPF recalculates; the ECMP candidate set changes. TCP flows on the affected path experience disruption.

Diagnostic: show ip ospf neighbor shows the neighbour transitioning states; show log protocol ospf shows the state changes.

The fix: investigate the link failure; the operator should not see frequent flaps in a healthy network.

Rollback

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

# Compare
compare

# Remove maximum-paths (revert to single-path)
delete protocols ospf parameters maximum-paths
commit

# Or reset the costs to default
delete protocols ospf interface eth0 cost
delete protocols ospf interface eth1 cost
commit

The rollback reverts the ECMP behaviour. The traffic returns to the single best path.

The disciplined rollback uses commit-confirm:

commit-confirm 5
# If the ECMP change has unintended consequences, the
# auto-rollback fires after 5 minutes.

Production discipline

Cross-course references

• Part XVIII-06 (XVIII-VyOS-OSPFFund / SPF and cost) covers the SPF algorithm and the cost calculation.
• Part XIX-06 (XIX-VyOS-OSPFConfig / cost tuning) covers the interface cost configuration.
• Part XXXVI-01 (XXXVI-VyOS-ECMP / concept) covers the conceptual model.
• Part XXXVI-02 (XXXVI-VyOS-ECMP / config) covers the general ECMP configuration including maximum-paths.
• Part XXXII (XXXII-VyOS-BFD) covers BFD for fast failure detection.

Quiz