show ip route: a legend that covers the table, and a default you can tell apart (#1234) #1236

Merged
jaylouisw merged 1 commit from fix/show-ip-route-legibility into main 2026-11-09 16:56:12 +00:00
Owner

show ip route: a legend that covers the table, and a default you can tell apart

Fixes #1234.

The routing table was correct and unreadable at the same time. Three things in what the command says:

  1. The legend was short. It named C and S while routesTable() also emits O (OSPF) and B
    (BGP) rows — so an OSPF-learned route printed as a code the legend never defined.
  2. The default gateway was labelled S, the same as a static route. It is not one: routeTo()
    treats it as a separate source with administrative distance 254, while a static route has distance 1.
    On a device with both, the table printed two identical-looking S 0.0.0.0/0 rows and gave no clue
    which was installed.
  3. The administrative distance was not shown, although it is half of the rule that picks the
    installed route (longest prefix first, then lowest distance).

Connected rows also printed via -, which reads as "no next hop" rather than "directly connected".

Now

Codes: C - connected, S - static, O - OSPF, B - BGP
Gateway of last resort is 10.1.2.1 to network 0.0.0.0
C   10.1.2.0       /24  is directly connected, Gi0
C   10.9.0.0       /24  is directly connected, Gi0/0/0
S  0.0.0.0        /0  [1/0] via 10.1.2.1
O  10.77.0.0      /16  [110/0] via 10.1.2.9  Gi0
B  203.0.113.0    /24  [20/0] via 10.1.2.2  Gi0
S* 0.0.0.0        /0  [254/0] via 10.1.2.254
  • the legend names every code the table can print;
  • [distance/metric] per row, from a single distanceOf() rule — connected 0, static 1, eBGP as
    configured (20 here), iBGP 200, OSPF 110, configured gateway 254;
  • the default gateway keeps its own form, S* (candidate default), so it can be told apart from
    ip route 0.0.0.0 0.0.0.0 …;
  • Gateway of last resort is … names the default that is installed, not merely the configured one.
    This matters: with a static default present, the gateway at 254 is not installed, and printing it
    would send the reader after a next hop no packet ever uses. My first version of this patch did exactly
    that, and the test caught it;
  • connected rows read is directly connected, <iface>.

Evidence

test/show-ip-route.test.js — 30 checks:

  • the legend explains C, S, O and B, and every code that appears in the body is defined (so
    a new route source cannot arrive without a legend entry);
  • connected rows say "is directly connected" and print no meaningless via -;
  • with both a static default and a configured gateway, both rows appear, S* vs S, [254/0] vs
    [1/0] — and they are no longer identical-looking;
  • distances: OSPF 110, eBGP 20, iBGP 200;
  • the gateway line names the installed default when both are configured, and the configured gateway when
    it is the only one;
  • a device with no default prints no gateway line and no S* row;
  • the printed table agrees with the data plane: for every prefix in the table, routeTo() on an
    address inside that prefix returns the type of the row that wins under "longest prefix, then lowest
    distance". That is the property that makes printing distances worth doing.

Reverting engine/cli.js fails 9 of them.

docs/CLI.md gains a "Reading show ip route" section with the two default forms and why S* is not
the installed default.

Suite: 133 suites, 5,810 assertions, 0 failed.

`show ip route`: a legend that covers the table, and a default you can tell apart Fixes #1234. The routing table was correct and unreadable at the same time. Three things in what the command *says*: 1. **The legend was short.** It named `C` and `S` while `routesTable()` also emits `O` (OSPF) and `B` (BGP) rows — so an OSPF-learned route printed as a code the legend never defined. 2. **The default gateway was labelled `S`, the same as a static route.** It is not one: `routeTo()` treats it as a separate source with administrative distance 254, while a static route has distance 1. On a device with both, the table printed two identical-looking `S 0.0.0.0/0` rows and gave no clue which was installed. 3. **The administrative distance was not shown**, although it is half of the rule that picks the installed route (longest prefix first, then lowest distance). Connected rows also printed `via -`, which reads as "no next hop" rather than "directly connected". ## Now ``` Codes: C - connected, S - static, O - OSPF, B - BGP Gateway of last resort is 10.1.2.1 to network 0.0.0.0 C 10.1.2.0 /24 is directly connected, Gi0 C 10.9.0.0 /24 is directly connected, Gi0/0/0 S 0.0.0.0 /0 [1/0] via 10.1.2.1 O 10.77.0.0 /16 [110/0] via 10.1.2.9 Gi0 B 203.0.113.0 /24 [20/0] via 10.1.2.2 Gi0 S* 0.0.0.0 /0 [254/0] via 10.1.2.254 ``` * the legend names every code the table can print; * `[distance/metric]` per row, from a single `distanceOf()` rule — connected 0, static 1, eBGP as configured (20 here), iBGP 200, OSPF 110, configured gateway 254; * the default gateway keeps its own form, `S*` (candidate default), so it can be told apart from `ip route 0.0.0.0 0.0.0.0 …`; * `Gateway of last resort is …` names the default **that is installed**, not merely the configured one. This matters: with a static default present, the gateway at 254 is *not* installed, and printing it would send the reader after a next hop no packet ever uses. My first version of this patch did exactly that, and the test caught it; * connected rows read `is directly connected, <iface>`. ## Evidence `test/show-ip-route.test.js` — 30 checks: * the legend explains `C`, `S`, `O` and `B`, and **every code that appears in the body is defined** (so a new route source cannot arrive without a legend entry); * connected rows say "is directly connected" and print no meaningless `via -`; * with both a static default and a configured gateway, both rows appear, `S*` vs `S`, `[254/0]` vs `[1/0]` — and they are no longer identical-looking; * distances: OSPF 110, eBGP 20, iBGP 200; * the gateway line names the installed default when both are configured, and the configured gateway when it is the only one; * a device with no default prints no gateway line and no `S*` row; * **the printed table agrees with the data plane**: for every prefix in the table, `routeTo()` on an address inside that prefix returns the type of the row that wins under "longest prefix, then lowest distance". That is the property that makes printing distances worth doing. Reverting `engine/cli.js` fails 9 of them. `docs/CLI.md` gains a "Reading `show ip route`" section with the two default forms and why `S*` is not the installed default. Suite: 133 suites, 5,810 assertions, 0 failed.
show ip route: a legend that covers the table, and a default you can tell apart
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 18) (pull_request) Successful in 1m53s
CI / Test (Node 20) (pull_request) Successful in 1m36s
CI / Server smoke test (pull_request) Successful in 25s
CI / Test (Node 22) (pull_request) Successful in 1m30s
CI / Docker build (pull_request) Successful in 43s
b5d38a7942
Fixes #1234.

The routing table was correct and unreadable at the same time. Three things in what the command *says*:

1. **The legend was short.** It named `C` and `S` while `routesTable()` also emits `O` (OSPF) and `B`
   (BGP) rows — so an OSPF-learned route printed as a code the legend never defined.
2. **The default gateway was labelled `S`, the same as a static route.** It is not one: `routeTo()`
   treats it as a separate source with administrative distance 254, while a static route has distance 1.
   On a device with both, the table printed two identical-looking `S 0.0.0.0/0` rows and gave no clue
   which was installed.
3. **The administrative distance was not shown**, although it is half of the rule that picks the
   installed route (longest prefix first, then lowest distance).

Connected rows also printed `via -`, which reads as "no next hop" rather than "directly connected".

## Now

```
Codes: C - connected, S - static, O - OSPF, B - BGP
Gateway of last resort is 10.1.2.1 to network 0.0.0.0
C   10.1.2.0       /24  is directly connected, Gi0
C   10.9.0.0       /24  is directly connected, Gi0/0/0
S  0.0.0.0        /0  [1/0] via 10.1.2.1
O  10.77.0.0      /16  [110/0] via 10.1.2.9  Gi0
B  203.0.113.0    /24  [20/0] via 10.1.2.2  Gi0
S* 0.0.0.0        /0  [254/0] via 10.1.2.254
```

* the legend names every code the table can print;
* `[distance/metric]` per row, from a single `distanceOf()` rule — connected 0, static 1, eBGP as
  configured (20 here), iBGP 200, OSPF 110, configured gateway 254;
* the default gateway keeps its own form, `S*` (candidate default), so it can be told apart from
  `ip route 0.0.0.0 0.0.0.0 …`;
* `Gateway of last resort is …` names the default **that is installed**, not merely the configured one.
  This matters: with a static default present, the gateway at 254 is *not* installed, and printing it
  would send the reader after a next hop no packet ever uses. My first version of this patch did exactly
  that, and the test caught it;
* connected rows read `is directly connected, <iface>`.

## Evidence

`test/show-ip-route.test.js` — 30 checks:

* the legend explains `C`, `S`, `O` and `B`, and **every code that appears in the body is defined** (so
  a new route source cannot arrive without a legend entry);
* connected rows say "is directly connected" and print no meaningless `via -`;
* with both a static default and a configured gateway, both rows appear, `S*` vs `S`, `[254/0]` vs
  `[1/0]` — and they are no longer identical-looking;
* distances: OSPF 110, eBGP 20, iBGP 200;
* the gateway line names the installed default when both are configured, and the configured gateway when
  it is the only one;
* a device with no default prints no gateway line and no `S*` row;
* **the printed table agrees with the data plane**: for every prefix in the table, `routeTo()` on an
  address inside that prefix returns the type of the row that wins under "longest prefix, then lowest
  distance". That is the property that makes printing distances worth doing.

Reverting `engine/cli.js` fails 9 of them.

`docs/CLI.md` gains a "Reading `show ip route`" section with the two default forms and why `S*` is not
the installed default.

Suite: 133 suites, 5,810 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 16:56:08 +00:00
jaylouisw force-pushed fix/show-ip-route-legibility from b5d38a7942
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 18) (pull_request) Successful in 1m53s
CI / Test (Node 20) (pull_request) Successful in 1m36s
CI / Server smoke test (pull_request) Successful in 25s
CI / Test (Node 22) (pull_request) Successful in 1m30s
CI / Docker build (pull_request) Successful in 43s
to fbe3eb0636
All checks were successful
CI / Classify the change (pull_request) Successful in 11s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 27s
CI / Test (Node 20) (pull_request) Successful in 1m38s
CI / Test (Node 18) (pull_request) Successful in 1m42s
CI / Server smoke test (pull_request) Successful in 34s
CI / Docker build (pull_request) Successful in 37s
CI / Test (Node 22) (pull_request) Successful in 1m36s
2026-11-09 16:56:08 +00:00
Compare
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1236
No description provided.