The DHCP server can say who holds which address, and a lapsed lease comes back (#1373) #1374

Merged
jaylouisw merged 1 commit from feat/dhcp-bindings into main 2026-11-10 19:28:40 +00:00
Owner

The DHCP server can now say who holds which address, and a lapsed lease comes back. Fixes #1373.

DHCP has been modelled end to end since it was: pools, ranges, exclusions, reservations, lease times, renewals and
expiry. The server keeps an allocation table — MAC → address, and when it comes back — and nothing could read
it
: there was no show ip dhcp at all. Same family as show power inline (#1295), the STP election (#1365), NAT
(#1367) and OSPF (#1371): the mechanism exists and the surface does not.

Two commands, reading the engine's own table

r1> show ip dhcp binding
IP address      Client identifier / MAC          Pool              Expires in
192.168.10.100  02:00:00:00:01:00                lan               3540s (0:59:00)
192.168.10.105  02:00:00:00:00:0a (reserved)     lan               3595s (0:59:55)

2 active binding(s); the lease clock runs from the instant the lease was granted
r1> show ip dhcp pool
Pool lan:
  Network:        192.168.10.0 255.255.255.0
  Range:          192.168.10.100 - 192.168.10.110
  Default router: 192.168.10.1
  DNS servers:    1.1.1.1
  Lease:          60s
  Excluded:       192.168.10.102
  Reservations:   192.168.10.105 (aa:bb:cc:00:00:99)
  In use:         2 of 10 address(es)
                  192.168.10.100 (02:00:00:00:01:00), 192.168.10.105 (02:00:00:00:00:0a)

Capacity is counted the way allocation counts it (dhcp.poolCapacity): endpoints in, network/broadcast out,
exclusions out, the gateway out when it sits inside the range. Reservations count, because they are allocatable to
their owner.

An unknown MAC, address or pool name is reported with the reason — never an empty table:

r1> show ip dhcp binding aa:bb:cc:dd:ee:ff
% No binding for aa:bb:cc:dd:ee:ff (no lease is held by that MAC)
r1> show ip dhcp pool guest
% No DHCP pool named guest (pools on this device: lan)
sw1> show ip dhcp binding
% This device is not a DHCP server (no "ip dhcp pool" configured)

A second defect, found while making the table readable

Nothing ever called expireLeases(). A lease that had lapsed held its address for the life of the run, so a
small pool could be exhausted by clients that were long gone — and show would have reported them as active
forever. Leases now expire at the instant the question is asked (runAtMs, converted into the seconds dhcp.js
counts in, in one place), and the lapsed row stays in the table marked lapsed (address free).

A third, found by probing the command I expected to work

host <mac> <address> is the same reservation as host <address> <mac>, and the handler stored it verbatim — so
the pool ended up keyed by the address, {"192.168.10.104": "aa:bb:cc:00:00:98"}, and said nothing until
exit refused the whole pool with "reservation key ... is not a valid MAC address". The two tokens are now told
apart by shape, both orders are accepted, and a pair that is neither is refused where it is typed, naming both
accepted orders.

Evidence

test/dhcp-bindings.test.js — 51 checks: the pool view is the pool the server answers from and its capacity is
counted the way allocation counts; bindings name their pool and lease length and match the address the client
actually holds; a binding can be asked for by MAC or address and an unknown one is reported; in a one-address
pool, a host that stops asking loses the address when its lease lapses and the other host gets it
(before the
fix the address was never freed and the second host was refused); a reserved address is marked; both reservation
orders store the same way round and a wrong pair is refused at the point of the typo; without a run the console
says nothing has been evaluated.

  • reverting engine/cli.js → 34 of 51 fail
  • reverting engine/dhcp.js or engine/simulator.js → the suite cannot run at all (poolCapacity,
    dhcpBindings)

help gains the command; docs/CLI.md gains "Reading DHCP"; docs/SIMULATION.md gains the row that says DHCP is
now reported and that expiry happens at the instant asked.

Suite: 190 suites, 7,352 assertions, 0 failed. Syntax: 258 files, OK.

The DHCP server can now say who holds which address, and a lapsed lease comes back. Fixes #1373. DHCP has been modelled end to end since it was: pools, ranges, exclusions, reservations, lease times, renewals and expiry. The server keeps an allocation table — MAC → address, and when it comes back — and **nothing could read it**: there was no `show ip dhcp` at all. Same family as `show power inline` (#1295), the STP election (#1365), NAT (#1367) and OSPF (#1371): the mechanism exists and the surface does not. ## Two commands, reading the engine's own table ``` r1> show ip dhcp binding IP address Client identifier / MAC Pool Expires in 192.168.10.100 02:00:00:00:01:00 lan 3540s (0:59:00) 192.168.10.105 02:00:00:00:00:0a (reserved) lan 3595s (0:59:55) 2 active binding(s); the lease clock runs from the instant the lease was granted ``` ``` r1> show ip dhcp pool Pool lan: Network: 192.168.10.0 255.255.255.0 Range: 192.168.10.100 - 192.168.10.110 Default router: 192.168.10.1 DNS servers: 1.1.1.1 Lease: 60s Excluded: 192.168.10.102 Reservations: 192.168.10.105 (aa:bb:cc:00:00:99) In use: 2 of 10 address(es) 192.168.10.100 (02:00:00:00:01:00), 192.168.10.105 (02:00:00:00:00:0a) ``` Capacity is counted the way allocation counts it (`dhcp.poolCapacity`): endpoints in, network/broadcast out, exclusions out, the gateway out when it sits inside the range. Reservations count, because they are allocatable to their owner. An unknown MAC, address or pool name is reported with the reason — never an empty table: ``` r1> show ip dhcp binding aa:bb:cc:dd:ee:ff % No binding for aa:bb:cc:dd:ee:ff (no lease is held by that MAC) r1> show ip dhcp pool guest % No DHCP pool named guest (pools on this device: lan) sw1> show ip dhcp binding % This device is not a DHCP server (no "ip dhcp pool" configured) ``` ## A second defect, found while making the table readable **Nothing ever called `expireLeases()`.** A lease that had lapsed held its address for the life of the run, so a small pool could be exhausted by clients that were long gone — and `show` would have reported them as active forever. Leases now expire at the instant the question is asked (`runAtMs`, converted into the seconds `dhcp.js` counts in, in one place), and the lapsed row stays in the table marked `lapsed (address free)`. ## A third, found by probing the command I expected to work `host <mac> <address>` is the same reservation as `host <address> <mac>`, and the handler stored it verbatim — so the pool ended up keyed by the **address**, `{"192.168.10.104": "aa:bb:cc:00:00:98"}`, and said nothing until `exit` refused the whole pool with *"reservation key ... is not a valid MAC address"*. The two tokens are now told apart by shape, both orders are accepted, and a pair that is neither is refused **where it is typed**, naming both accepted orders. ## Evidence `test/dhcp-bindings.test.js` — **51 checks**: the pool view is the pool the server answers from and its capacity is counted the way allocation counts; bindings name their pool and lease length and match the address the client actually holds; a binding can be asked for by MAC or address and an unknown one is reported; **in a one-address pool, a host that stops asking loses the address when its lease lapses and the other host gets it** (before the fix the address was never freed and the second host was refused); a reserved address is marked; both reservation orders store the same way round and a wrong pair is refused at the point of the typo; without a run the console says nothing has been evaluated. * reverting `engine/cli.js` → **34 of 51 fail** * reverting `engine/dhcp.js` or `engine/simulator.js` → the suite cannot run at all (`poolCapacity`, `dhcpBindings`) `help` gains the command; `docs/CLI.md` gains "Reading DHCP"; `docs/SIMULATION.md` gains the row that says DHCP is now reported and that expiry happens at the instant asked. Suite: **190 suites, 7,352 assertions, 0 failed**. Syntax: 258 files, OK.
The DHCP server can say who holds which address, and a lapsed lease comes back (#1373)
All checks were successful
CI / Classify the change (pull_request) Successful in 18s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 23s
CI / Test (Node 20) (pull_request) Successful in 2m43s
CI / Test (Node 18) (pull_request) Successful in 2m55s
CI / Server smoke test (pull_request) Successful in 29s
CI / Docker build (pull_request) Successful in 1m0s
CI / Test (Node 22) (pull_request) Successful in 2m20s
0e59b3db38
DHCP has been modelled end to end since it was: pools, ranges, exclusions, reservations, lease times,
renewals and expiry. The server keeps an allocation table - MAC -> address, and when it comes back - and
nothing could read it: there was no 'show ip dhcp' at all. Same family as show power inline (#1295), the
STP election (#1365), NAT (#1367) and OSPF (#1371): the mechanism exists and the surface does not.

Two commands, reading the engine's own table:

  show ip dhcp binding [<address|mac>]   address, MAC, pool, time left; '(reserved)' marks an address
                                         pinned to that MAC; a lapsed row reads 'lapsed (address free)'
  show ip dhcp pool [<name>]             network, range, gateway, DNS, lease, exclusions, reservations,
                                         and 'In use: N of M address(es)' with the holders listed

Capacity is counted the way allocation counts (dhcp.poolCapacity): endpoints in, network/broadcast out,
exclusions out, the gateway out when it sits inside the range. An unknown MAC, address or pool name is
reported with the reason; a device with no pools says it is not a DHCP server; a device with pools and no
run says the binding state has not been evaluated rather than printing an empty table.

THE OTHER DEFECT, found while making the table readable: nothing ever called expireLeases(). A lease that
had lapsed held its address for the life of the run, so a small pool could be exhausted by clients that
were long gone and 'show' would have reported them as active forever. Leases now expire at the instant the
question is asked (runAtMs, in the seconds dhcp.js counts in) and the expired row stays in the table,
marked, so an address that is stuck can be explained.

AND A THIRD, found by probing the command I expected to work: 'host <mac> <address>' is the same
reservation as 'host <address> <mac>', and the handler stored it verbatim, so the pool ended up keyed by
the address - {"192.168.10.104": "aa:bb:cc:00:00:98"} - and said nothing until 'exit' refused the whole
pool with "reservation key ... is not a valid MAC address". The two tokens are now told apart by shape,
both orders are accepted, and a pair that is neither is refused where it is typed, naming both orders.

Evidence: test/dhcp-bindings.test.js, 51 checks - the pool view is the pool the server answers from and its
capacity is counted the way allocation counts; bindings name the pool and the lease length and match the
address the client actually holds; a binding can be asked for by MAC or address and an unknown one is
reported; in a one-address pool, a host that stops asking loses the address when its lease lapses and the
other host gets it (before the fix the address was never freed and the second host was refused); a reserved
address is marked; both reservation orders store the same way round and a wrong pair is refused at the
point of the typo; and without a run the console says nothing has been evaluated. Reverting engine/cli.js
fails 34 of 51; reverting engine/dhcp.js or engine/simulator.js leaves the suite unable to run at all.

help gains the command; docs/CLI.md gains 'Reading DHCP'; docs/SIMULATION.md gains the row that says DHCP
is now reported and that expiry happens at the instant asked.

Suite: 190 suites, 7,352 assertions, 0 failed. Syntax: 258 files, OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 19:28: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!1374
No description provided.