SonicLab18 lessons · Available
On this page
L3 forwarding · Practical operator lesson

Static Routes and Forwarding

Install one remote route through an adjacent router, verify the return route, and separate intent from delivery.

Prerequisite: Routed Interfaces and Neighbor ResolutionScenario → configuration → state → evidence → fault / repair
By the end, you should be able to:
  • Configure one explicit next-hop route and a matching return route.
  • Compare CONFIG_DB intent, routing selection, programming evidence, and packets.
  • Repair a deleted-route fault without creating an accidental additional path.

Community SONiC 202505 source baseline; single ASIC, default namespace, community CLI. Virtual feature support and physical ASIC behavior differ. All commands and output are illustrative; no lab was executed.

Scenario: a remote subnet through one next hop

S1 and R1 are separate SONiC devices using the same checked community CLI. Their physical ports are reserved, routed, and outside VLAN/LAG membership. Host addresses and gateways are prepared as shown. There is no default route, alternate path, or overlapping route covering these lab destinations.

A static route needs a return path
A static route needs a return pathHost A eth1 192.0.2.10/24 gateway192.0.2.1 connects to S1 Ethernet0 192.0.2.1/24. S1 Ethernet4 198.51.100.1/30 connects to R1 Ethernet0 198.51.100.2/30. R1 Ethernet4 203.0.113.1/24 connects to Host B eth1 203.0.113.10/24 gateway203.0.113.1. S1 has a route for 203.0.113.0/24 via198.51.100.2; R1 has a return route for192.0.2.0/24 via198.51.100.1.Host A · eth1192.0.2.10/24S1E0: 192.0.2.1/24R1E4: 203.0.113.1/24Host B · eth1203.0.113.10/24E4: 198.51.100.1/30E0: 198.51.100.2/30Transit subnet 198.51.100.0/30GW 192.0.2.1GW 203.0.113.1S1: 203.0.113.0/24 → 198.51.100.2, Ethernet4R1: 192.0.2.0/24 → 198.51.100.1, Ethernet0E0 / E4 abbreviate Ethernet0 / Ethernet4. Forward and return paths are both required.
Original physical topology. Endpoint and router labels belong to separate devices; no addresses are borrowed from earlier running labs.
Lab contract: isolated, reserved ports and documentation addresses; independent management access. Starting baseline: listed switch ports administratively down, no lab addresses or VLAN/LAG membership, and no lab static routes; endpoints already prepared as shown. Record and verify that baseline first. If it differs, adapt the plan rather than overwrite existing state. Use the before-state method from lesson 06. No example saves startup configuration. All output and packet results are illustrative, not live observations.

Configuration: adjacent next hop, explicit remote route

# S1 only
sudo config interface ip add Ethernet0 192.0.2.1/24
sudo config interface ip add Ethernet4 198.51.100.1/30
sudo config interface startup Ethernet0
sudo config interface startup Ethernet4
sudo config route add prefix 203.0.113.0/24 nexthop 198.51.100.2 dev Ethernet4
# R1 only
sudo config interface ip add Ethernet0 198.51.100.2/30
sudo config interface ip add Ethernet4 203.0.113.1/24
sudo config interface startup Ethernet0
sudo config interface startup Ethernet4
sudo config route add prefix 192.0.2.0/24 nexthop 198.51.100.1 dev Ethernet0

Separate SONiC setup sequences; execute neither from this page. Illustrative only; not executed on a SONiC device.

The remote destination is 203.0.113.0/24; S1’s immediate next hop is the adjacent 198.51.100.2, not Host B itself. R1 needs the return route to A’s subnet. Endpoint gateways must also be correct. This assumes CONFIG_DB-integrated static routing is enabled and supported by the selected image.

The checked CLI writes STATIC_ROUTE intent; the checked static-route manager translates it for the routing service. Direct FRR edits use a different management path and are not substituted here.

Read further: 202505 configuration CLI implementation · 202505 static-route manager.

State: inspect four boundaries

# S1 only — read-only
sonic-db-cli CONFIG_DB HGETALL "STATIC_ROUTE|203.0.113.0/24"
show ip route 203.0.113.10
show arp
show interfaces status Ethernet4
# R1 only — read-only
show ip route 192.0.2.10
show arp

Single-ASIC, default-namespace inspection. No database writes are used. Illustrative only; not executed on a SONiC device.

# S1 CONFIG_DB excerpt
nexthop: 198.51.100.2
ifname: Ethernet4
# Separate S1 routing-view excerpt
S>* 203.0.113.0/24 [1/0] via 198.51.100.2, Ethernet4

Invented reformatted excerpts, not literal combined output. Other fields and route entries are omitted.

  1. Intent: the configured prefix, next hop, and interface are correct.
  2. RIB / routing view: the intended route is selected, not merely configured.
  3. Programming: next-hop dependencies, orchestration, SAI responses, and platform evidence support installation. A routing-stack * marker or an ASIC_DB entry alone is not independent hardware proof.
  4. Delivery: endpoint traffic and return-path evidence confirm the tested exchange.

Read further: 202505 command reference (pinned) · Windows cross-check revision: route orchestration · Windows cross-check revision: SAI Redis and syncd.

Forwarding evidence: keep destination and next hop distinct

On Host A, ping -c 3 203.0.113.10 would test the round trip. A first sends to S1’s gateway MAC. S1 looks up the remote destination, resolves R1’s transit MAC, and rewrites the Ethernet header toward R1. R1 performs its own lookup and neighbor resolution toward B. Replies follow the configured return route.

Compare bounded endpoint results, the two transit adjacencies, and captures/counters with timestamps. A hypothetical 3/3 reply result confirms only that tested path and moment, not scale, convergence, or line-rate performance.

ECMP: multiple equal-cost next hops is available as a focused lesson. This single-next-hop scenario neither tests hardware hash distribution nor proves that several equal routes share traffic in a particular way.

Fault and repair: remove S1’s remote route

# S1 only — remove the exact lab path
sudo config route del prefix 203.0.113.0/24 nexthop 198.51.100.2 dev Ethernet4
show ip route 203.0.113.10
show arp

Controlled static-route fault on S1; R1’s return route is left intact. Illustrative only; not executed on a SONiC device.

With no covering alternative in this isolated baseline, S1 no longer has the intended route for B. Its adjacency to 198.51.100.2 can remain healthy. A-to-B traffic should fail after state converges even though the link and ARP entry look good. Inspect the actual lookup: a default or more-specific route on a different setup could change that result.

# S1 only — add the removed path once
sudo config route add prefix 203.0.113.0/24 nexthop 198.51.100.2 dev Ethernet4
show ip route 203.0.113.10
show arp

Exact repair for the route that was removed. Illustrative only; not executed on a SONiC device.

Recheck route selection, downstream programming evidence, R1’s return route, and endpoint traffic. Do not repeatedly add a route as a replacement strategy: on the checked CLI, add can append next-hop data to an existing prefix. Verify intent before adding.

For full teardown after route repair, remove the exact two added paths before removing the interface addresses. This restores the stated no-lab-route/no-lab-address/admin-down baseline; endpoint preparation remains unchanged.

# S1 only
sudo config route del prefix 203.0.113.0/24 nexthop 198.51.100.2 dev Ethernet4
sudo config interface ip remove Ethernet0 192.0.2.1/24
sudo config interface ip remove Ethernet4 198.51.100.1/30
sudo config interface shutdown Ethernet0
sudo config interface shutdown Ethernet4
# R1 only
sudo config route del prefix 192.0.2.0/24 nexthop 198.51.100.1 dev Ethernet0
sudo config interface ip remove Ethernet0 198.51.100.2/30
sudo config interface ip remove Ethernet4 203.0.113.1/24
sudo config interface shutdown Ethernet0
sudo config interface shutdown Ethernet4

Separate device teardown sequences; never remove a shared route or address. Illustrative only; not executed on a SONiC device.

On both devices, recheck interface addresses, route lookups, and administrative states against the before record. Startup files remain unchanged; no reboot or blanket reload is used.

Key takeaways

  • A remote prefix and its immediate next hop are different addresses with different jobs.
  • The adjacent next hop needs a usable interface and local neighbor resolution.
  • Intent, route selection, programming evidence, and packet delivery are distinct checks.
  • Return routes and endpoint gateways are essential to a round trip.
  • Repair the exact route once; ECMP and hardware distribution remain a separate focused topic.

Check your understanding

Six questions, four choices each. Review the explanation after each answer, then see your score and retry.

Sources & baseline

Reviewed 18 October 2026. Community source pins: sonic-utilities 7511bf2f8ea3582c2b67cf5016f8e8237e62882b; sonic-buildimage ff3c0c9f686a1d0dbddbe813b233b3b7a51bd8e2. Confirm image support and local help; these pins are not a claim about a deployed binary.

Additional Windows code inspection: buildimage 128f6802b6e1, utilities cc4fbb3e8313, SWSS b8a9b65494c2. The static-route manager is inside sonic-buildimage, not a separate checked-out repository. These are different revisions from the release baseline. Exact paths and checks are recorded in SOURCE-REVIEW.txt.

Lesson 09 · Knowledge check