cli(traceroute): max <n> caps the walk the index has promised since #1484 #2437

Merged
jaylouisw merged 1 commit from rev/1121-1442 into main 2026-11-21 15:08:01 +00:00
Owner

Question

A Cisco-style box's traceroute hop cap: what it is called on the line, what range it accepts, and what the box prints after the last hop when the cap - not the destination - ended the walk.

help has advertised traceroute|tracert <address|name> [max <n>] since #1484, and docs/CLI.md recorded the row as "indexed and not implemented": _traceroute() read tokens[0] only, so max 5 was swallowed in silence and every trace ran thirty hops - while Simulator.traceroute() has taken opts.maxHops all along (its tests exercise 1, 2, 3 and 5).

Evidence

  • Cisco doc 13730, extended traceroute: Maximum Time to Live [30] - "The traceroute command terminates when the destination is reached or when this value is reached." No closing line is described; the worked capture ends at the last hop.
  • Cisco CBS 250/350 CLI reference: traceroute ip {...} [ttl max-ttl] with ttl max-ttl ... (Range: 1-255), default 30; "terminates when the destination responds, when the maximum TTL is exceeded, or when the user interrupts".
  • Cisco ASA command reference (T-Z): ttl min_ttl max_ttl; max-ttl "The largest TTL value that can be used. The default is 30. The command terminates ... when the value is reached."
  • Cisco NFVIS command reference: the keyword is exactly [max max], "the maximum time-to-live (TTL) ... default value is 30" (its output shape is Linux's, not IOS's).
  • Cisco ASR 5000 (T-Z): maxttl "an integer from 1 through 255 ... Default: 30".

Verdict: the cap exists on every IOS-family form, defaults to 30, accepts 1-255, and nothing is printed after the last hop. The keyword is split across platforms (ttl <max>, ttl <min> <max>, max, maxttl); classic IOS has only the interactive prompt.

What changed

  • engine/cli.js _traceroute(): parses max <n> after the target, validates 1-255, refuses (by name, no probe sent) a missing value, a non-numeric or out-of-range value, a second max, and any other word after the target; passes { maxHops: n } to the walk.
  • engine/simulator.js: maxHops clamp 64 -> 255, so an accepted value is the value used.
  • The unfinished-walk sentence is singular for one hop (after 1 hop).
  • help now reads [max <1-255>]; docs/CLI.md gains "The hop limit" and stops calling the row half-implemented.
  • research/traceroute-hop-cap.md: evidence table, verdict, unadopted spellings, open questions.
  • test/traceroute-max-hops.test.js: 34 assertions.

Gates

  • node scripts/syntax-check.js: 538 files OK.
  • npm test: 458 suites, 15535 assertions, 0 failed.

Unresolved

Which keyword an IOS-faithful console should adopt (ttl forms not added - a second grammar, not the completion of this one); the min lower bound and how hop numbers are numbered when it is used; a capture of a cap hit on a silent tail; probe/timeout keywords are out of scope.

## Question A Cisco-style box's `traceroute` hop cap: what it is called on the line, what range it accepts, and what the box prints after the last hop when the cap - not the destination - ended the walk. `help` has advertised `traceroute|tracert <address|name> [max <n>]` since #1484, and `docs/CLI.md` recorded the row as "indexed and not implemented": `_traceroute()` read `tokens[0]` only, so `max 5` was swallowed in silence and every trace ran thirty hops - while `Simulator.traceroute()` has taken `opts.maxHops` all along (its tests exercise 1, 2, 3 and 5). ## Evidence * Cisco doc 13730, extended traceroute: `Maximum Time to Live [30]` - "The traceroute command terminates when the destination is reached or when this value is reached." No closing line is described; the worked capture ends at the last hop. * Cisco CBS 250/350 CLI reference: `traceroute ip {...} [ttl max-ttl]` with `ttl max-ttl ... (Range: 1-255)`, default 30; "terminates when the destination responds, when the maximum TTL is exceeded, or when the user interrupts". * Cisco ASA command reference (T-Z): `ttl min_ttl max_ttl`; `max-ttl` "The largest TTL value that can be used. The default is 30. The command terminates ... when the value is reached." * Cisco NFVIS command reference: the keyword is exactly `[max max]`, "the maximum time-to-live (TTL) ... default value is 30" (its output shape is Linux's, not IOS's). * Cisco ASR 5000 (T-Z): `maxttl` "an integer from 1 through 255 ... Default: 30". Verdict: the cap exists on every IOS-family form, defaults to 30, accepts 1-255, and nothing is printed after the last hop. The keyword is split across platforms (`ttl <max>`, `ttl <min> <max>`, `max`, `maxttl`); classic IOS has only the interactive prompt. ## What changed * `engine/cli.js` `_traceroute()`: parses `max <n>` after the target, validates 1-255, refuses (by name, no probe sent) a missing value, a non-numeric or out-of-range value, a second `max`, and any other word after the target; passes `{ maxHops: n }` to the walk. * `engine/simulator.js`: `maxHops` clamp 64 -> 255, so an accepted value is the value used. * The unfinished-walk sentence is singular for one hop (`after 1 hop`). * `help` now reads `[max <1-255>]`; `docs/CLI.md` gains "The hop limit" and stops calling the row half-implemented. * `research/traceroute-hop-cap.md`: evidence table, verdict, unadopted spellings, open questions. * `test/traceroute-max-hops.test.js`: 34 assertions. ## Gates * `node scripts/syntax-check.js`: 538 files OK. * `npm test`: **458 suites, 15535 assertions, 0 failed**. ## Unresolved Which keyword an IOS-faithful console should adopt (`ttl` forms not added - a second grammar, not the completion of this one); the `min` lower bound and how hop numbers are numbered when it is used; a capture of a cap hit on a silent tail; `probe`/`timeout` keywords are out of scope.
cli(traceroute): max <n> caps the walk the index has promised since #1484 (#2437)
All checks were successful
CI / Server smoke and Docker build (pull_request) Successful in 24s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 8s
CI / Test (Node 20) (pull_request) Successful in 59s
CI / Test (Node 22) (pull_request) Successful in 1m0s
CI / Test (Node 18) (pull_request) Successful in 1m3s
CI / Arm auto-merge (pull_request) Successful in 3s
15db5af4b9
`help` printed `traceroute <target> [max <n>]` and docs/CLI.md recorded the row as indexed and not
implemented: _traceroute() read tokens[0] only, so `max 5` was swallowed and every trace ran thirty hops
while Simulator.traceroute() has taken opts.maxHops all along.

Parsed and validated 1-255 (CBS 250/350 "Range: 1-255", ASR 5000 "1 through 255"), refused by name rather
than ignored when missing, non-numeric, out of range, given twice, or followed by another word. The walk gets
the cap; the simulator's own clamp moves 64 -> 255 so an accepted value is the value used. The unfinished-walk
sentence is singular for one hop.

research/traceroute-hop-cap.md collects the references (13730, CBS 250/350, ASA T-Z, NFVIS, ASR 5000), the two
unadopted spellings (ttl <max>, ttl <min> <max>) and what is still open.
test/traceroute-max-hops.test.js: 34 assertions.
forgejo-actions scheduled this pull request to auto merge when all checks succeed 2026-11-21 14:53:58 +00:00
forgejo-actions canceled auto merging this pull request when all checks succeed 2026-11-21 15:01:04 +00:00
jaylouisw referenced this pull request from a commit 2026-11-21 15:08:02 +00:00
jaylouisw deleted branch rev/1121-1442 2026-11-21 15:08:10 +00:00
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!2437
No description provided.