NAT from the console, and a ping that is actually translated (#1366) #1367

Merged
jaylouisw merged 1 commit from feat/nat-console into main 2026-11-10 18:09:37 +00:00
Owner

NAT from the console, and a ping that is actually translated. Fixes #1366.

engine/nat.js models static, dynamic and PAT translation with a live table and ageing, and the flow path calls
it on the way out and back in, emitting nat-drop when a rule cannot translate. Nothing in the product ever
wrote config.nat
— not the CLI, not the UI, not the server, not a catalogue spec — so _isNat() was always
false and docs/SIMULATION.md carried an "Absent in the CLI" row next to it.

Worse, the one test anybody runs was wrong even with rules in the file. Both hooks began:

if (!frame || !frame.l4 || !this._isNat(dev)) return 'pass';

An ICMP echo has no l4 — the engine keeps it in frame.icmp — so a ping crossed a NAT router untouched. The
docs recorded that too, as "Absent — important".

The console

ip nat pool WAN 203.0.113.1 203.0.113.1 netmask 255.255.255.0
ip nat inside source list 192.168.10.0/24 pool WAN overload
ip nat inside source static 192.168.10.60 203.0.113.1 tcp 443
no ip nat inside source
no ip nat pool WAN

Every rule is validated by nat.js's own validateRule(), so the console and the data path cannot disagree about
what a rule means. Refusals name the reason and what would work:

% PAT overloads one address; pool "TWO" holds more than one. Use a single-address pool for overload,
  or drop `overload` for a dynamic pool
% 10 is an ACL number: this model takes the inside local addresses here, e.g. `list 192.168.1.0/24`
% Gi0/0/3 has no address: there is nothing for NAT to translate to
% NAT pool "WAN" ends before it starts (203.0.113.9 - 203.0.113.1)
% NAT pool "WAN" is still used by 1 rule(s): remove those first

The reports

show ip nat rules          # each rule as the command that would create it
show ip nat translations   # the live table, with its header
show ip nat statistics     # rules by type, pools, active translations

show ip nat translations distinguishes nothing has crossed (No translations: no packet needing NAT has crossed this device) from traffic crossed and nothing needed translating — the same distinction
show interfaces makes for its counters.

ICMP

The packet view now comes from frame.icmp when there is no l4; only the address is rewritten (an echo is
identified by its id, not a port), and the events report proto icmp with a null port instead of dereferencing
an l4 that is not there. Measured on an inside host at 192.168.10.50 behind a PAT pool:

in1> ping 203.0.113.9
!!!!   Success rate is 100 percent (4/4)

r1> show ip nat translations
Pro  Inside global          Inside local           Outside local          Outside global
icmp 203.0.113.1:1024       192.168.10.50          203.0.113.9            203.0.113.9

Survives a save

Serialized only when non-empty, restored on load, and printed by show running-config pools before the rules
that name them
, so a restore replays. test/config-completeness.test.js gains the print declaration the suite
demands for a new config key (56 checks).

Evidence

test/nat-cli.test.js — 38 checks: pool and rule creation, seven kinds of refusal, a real ping translated
through PAT with the inside local and inside global in the table, the three report views, a lab with no rules that
still pings and says so, static port forwarding, save/reload, and the no forms.

  • reverting engine/cli.js → 21 of 38 fail
  • reverting engine/simulator.js → 7 of 38 fail (every translation check)

docs/CLI.md gains the command table, the refusals and the three show views; docs/SIMULATION.md's two "Absent"
rows for NAT become "Modelled"; docs/ROADMAP.md's NAT item is ticked.

npm run syntax — 254 files, all OK. npm test — 186 suites, 7,211 assertions, 0 failed.

NAT from the console, and a ping that is actually translated. Fixes #1366. `engine/nat.js` models static, dynamic and PAT translation with a live table and ageing, and the flow path calls it on the way out and back in, emitting `nat-drop` when a rule cannot translate. **Nothing in the product ever wrote `config.nat`** — not the CLI, not the UI, not the server, not a catalogue spec — so `_isNat()` was always false and `docs/SIMULATION.md` carried an "Absent in the CLI" row next to it. Worse, the one test anybody runs was wrong even with rules in the file. Both hooks began: ```js if (!frame || !frame.l4 || !this._isNat(dev)) return 'pass'; ``` An ICMP echo has no `l4` — the engine keeps it in `frame.icmp` — so a ping crossed a NAT router untouched. The docs recorded that too, as **"Absent — important"**. ## The console ``` ip nat pool WAN 203.0.113.1 203.0.113.1 netmask 255.255.255.0 ip nat inside source list 192.168.10.0/24 pool WAN overload ip nat inside source static 192.168.10.60 203.0.113.1 tcp 443 no ip nat inside source no ip nat pool WAN ``` Every rule is validated by `nat.js`'s own `validateRule()`, so the console and the data path cannot disagree about what a rule means. Refusals name the reason and what would work: ``` % PAT overloads one address; pool "TWO" holds more than one. Use a single-address pool for overload, or drop `overload` for a dynamic pool % 10 is an ACL number: this model takes the inside local addresses here, e.g. `list 192.168.1.0/24` % Gi0/0/3 has no address: there is nothing for NAT to translate to % NAT pool "WAN" ends before it starts (203.0.113.9 - 203.0.113.1) % NAT pool "WAN" is still used by 1 rule(s): remove those first ``` ## The reports ``` show ip nat rules # each rule as the command that would create it show ip nat translations # the live table, with its header show ip nat statistics # rules by type, pools, active translations ``` `show ip nat translations` distinguishes *nothing has crossed* (`No translations: no packet needing NAT has crossed this device`) from *traffic crossed and nothing needed translating* — the same distinction `show interfaces` makes for its counters. ## ICMP The packet view now comes from `frame.icmp` when there is no `l4`; only the address is rewritten (an echo is identified by its id, not a port), and the events report `proto icmp` with a null port instead of dereferencing an `l4` that is not there. Measured on an inside host at `192.168.10.50` behind a PAT pool: ``` in1> ping 203.0.113.9 !!!! Success rate is 100 percent (4/4) r1> show ip nat translations Pro Inside global Inside local Outside local Outside global icmp 203.0.113.1:1024 192.168.10.50 203.0.113.9 203.0.113.9 ``` ## Survives a save Serialized only when non-empty, restored on load, and printed by `show running-config` **pools before the rules that name them**, so a restore replays. `test/config-completeness.test.js` gains the print declaration the suite demands for a new config key (56 checks). ## Evidence `test/nat-cli.test.js` — **38 checks**: pool and rule creation, seven kinds of refusal, a real ping translated through PAT with the inside local and inside global in the table, the three report views, a lab with no rules that still pings and says so, static port forwarding, save/reload, and the `no` forms. * reverting `engine/cli.js` → **21 of 38 fail** * reverting `engine/simulator.js` → **7 of 38 fail** (every translation check) `docs/CLI.md` gains the command table, the refusals and the three show views; `docs/SIMULATION.md`'s two "Absent" rows for NAT become "Modelled"; `docs/ROADMAP.md`'s NAT item is ticked. `npm run syntax` — 254 files, all OK. `npm test` — **186 suites, 7,211 assertions, 0 failed**.
NAT from the console, and a ping that is actually translated (#1366)
Some checks failed
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 17s
CI / Test (Node 20) (pull_request) Failing after 2m58s
CI / Test (Node 18) (pull_request) Successful in 3m4s
CI / Server smoke test (pull_request) Successful in 36s
CI / Docker build (pull_request) Successful in 45s
CI / Test (Node 22) (pull_request) Successful in 2m17s
a8b3dac311
engine/nat.js models static, dynamic and PAT translation with a live table and ageing, and the flow path
calls it on the way out and back in, emitting nat-drop when a rule cannot translate. Nothing in the
product ever wrote config.nat: not the CLI, not the UI, not the server, not a catalogue spec. So
Simulator._isNat() was always false, the whole mechanism was unreachable, and docs/SIMULATION.md carried
'Absent in the CLI' next to it.

Worse, the one test anybody runs was wrong even with rules in the file. _natOutbound/_natInbound began

    if (!frame || !frame.l4 || !this._isNat(dev)) return 'pass';

and an ICMP echo has no l4 - the engine keeps it in frame.icmp. A ping therefore crossed a NAT router
untouched, and the same docs section recorded it as 'Absent - important'.

Now:

- ip nat pool <name> <start> <end> netmask <mask>
- ip nat inside source static <local> <global> [tcp|udp <port>]
- ip nat inside source list <spec> pool <name> [overload]
- ip nat inside source list <spec> interface <if> [overload]
- no ip nat inside source | no ip nat pool <name>

Every rule is validated by nat.js's own validateRule(), so the console and the data path cannot disagree
about what a rule means. Refusals name the reason and what would work: overload on a multi-address pool,
an ACL number where this model takes an address spec, an interface with no address, a pool that ends
before it starts, a duplicate pool name, a pool still in use.

show ip nat rules prints each rule as the command that would create it; show ip nat translations prints
the engine's live table with its header; show ip nat statistics counts rules by type, pools and active
translations. 'Nothing has crossed' and 'traffic crossed and nothing needed translating' are different
answers and the report gives both.

ICMP now reaches NAT: the packet view comes from frame.icmp when there is no l4, only the address is
rewritten (an echo is identified by its id, not a port), and the events report proto icmp with a null
port rather than dereferencing an l4 that is not there.

The config survives a save (serialized only when non-empty, restored on load) and show running-config
prints pools before the rules that name them, so a restore replays.

test/nat-cli.test.js: 38 checks - pool and rule creation, seven kinds of refusal, a real ping translated
through PAT with the inside local and inside global in the table, the report's three views, a lab with no
rules that still pings and says so, static port forwarding, save/reload, and the no-forms. Reverting
engine/cli.js fails 21 of 38; reverting engine/simulator.js fails 7 (every translation check).

test/config-completeness.test.js gains the print declaration for the new config key (56 checks).

docs: CLI.md gains the command table, the refusals and the three show views; SIMULATION.md's two 'Absent'
rows for NAT become 'Modelled'; ROADMAP's NAT item is ticked.

Suite: 186 suites, 7,211 assertions, 0 failed. Syntax: 254 files, all OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 18:09:34 +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!1367
No description provided.