HTTPS on port 10443 on the gateway, with a self-signed certificate made at install. Clients
must either trust that certificate or skip verification (curl -k). No authentication yet.
Base path: /v1. The retired Raspberry Pi build served the same API.
Devices under test join one of two test SSIDs, each on its own VLAN:
| SSID | Subnet | Gateway bridge |
|---|---|---|
test-a |
192.0.2.0/24 |
br10 |
test-b |
198.51.100.0/24 |
br20 |
The gateway routes between VLANs in software, so traffic between a test-VLAN device and anything on another network — the main LAN, the other test VLAN, the internet — passes through its kernel and can be conditioned. Traffic between two devices on the same test VLAN is switched by the AP and switch, never reaches the gateway, and cannot be shaped.
A shape targets a device's IP. An IP outside the test subnets is accepted, but the response carries a warning: its traffic never reaches the shaper.
When both ends of a flow are shaped - one device on each test VLAN - both shapes apply: the sender's upload shape and the receiver's download shape stack.
POST /v1/shape is declarative by default: the array you send becomes the complete set of
active shapes, and any IP not in the array is returned to unshaped. This makes repeated calls
safe and free of state drift - you never need to clear before setting.
Pass "merge": true to touch only the IPs you list and leave every other device's shaping alone.
| Field | Type | Default | Meaning |
|---|---|---|---|
ip |
IPv4 string | required | Device to shape |
latencyMs |
number ≥ 0 | 0 |
Delay added in each direction |
jitterMs |
number ≥ 0 | 0 |
Uniform jitter, giving latencyMs ± jitterMs |
mbit |
number ≥ 0 | 0 |
Bandwidth cap, fractions allowed. 0 = uncapped |
lossPct |
number ≥ 0 | 0 |
Random packet loss percentage |
Top-level alongside shapes:
| Field | Type | Default | Meaning |
|---|---|---|---|
merge |
boolean | false |
Only touch the listed IPs, leaving others alone |
An entry naming an IP with no conditioning on it - { "ip": "..." }, or every field zero - means
"this device is unshaped", and clears anything already applied to it. Combine that with merge
to undo one device without disturbing the rest:
# clear 192.0.2.10, leave every other shaped device exactly as it was
curl -sk -X POST https://gateway.example:10443/v1/shape -H 'Content-Type: application/json' \
-d '{"merge":true,"shapes":[{"ip":"192.0.2.10"}]}'Without merge, that same call also clears everything you did not list, because the array is
the complete desired state. Clearing an IP that was never shaped is a harmless no-op, and
shaping and clearing can be mixed in one call:
curl -sk -X POST https://gateway.example:10443/v1/shape -H 'Content-Type: application/json' \
-d '{"merge":true,"shapes":[
{"ip":"192.0.2.10"},
{"ip":"192.0.2.20","latencyMs":250,"mbit":0.5}
]}'latencyMs is one-way per direction, so round-trip latency rises by roughly
2 × latencyMs. A latencyMs of 100 produces about 200 ms of added ping time - measured
211 ms against a 9 ms baseline. The response returns expectedRttDeltaMs so this is never
ambiguous.
Response:
{
"ok": true,
"merge": false,
"cleared": ["192.0.2.20"], // IPs returned to unshaped by this call
"applied": [
{ "ip": "192.0.2.10", "latencyMs": 120, "jitterMs": 0, "mbit": 1.5,
"lossPct": 0, "slot": 1, "expectedRttDeltaMs": 240 }
],
"applyDurationMs": 6.1, // whole request, server side
"tcDurationMs": 5.4, // time inside the single tc invocation
"commandCount": 8,
"warnings": [] // e.g. an IP that is not on a test VLAN
}Up to 32 devices may be shaped simultaneously. Beyond that the extra shapes are dropped and
named in warnings.
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/health |
{ ok, version, iface, interfaces, radios, uptimeMs, treeIntact, activeCount, maxSlots } |
GET |
/v1/shape |
Current active shapes |
DELETE |
/v1/shape |
Clear all shaping |
POST |
/v1/reset |
Tear down and rebuild the whole tc tree |
GET |
/v1/devices |
Clients on the test VLANs, with IP, network, SSID and hostname |
GET |
/v1/stats |
Raw tc -s class counters for both directions |
GET |
/v1/history |
Every shaping change, newest first: time, caller IP, request, result. ?limit=N |
interfaces in /v1/health lists each shaped bridge with name, ssid, subnet, present
and hooked (shaping is attached to it). radios is the same list under the Pi build's name.
GET /v1/devices is how a test agent discovers what it can shape without hard-coding
addresses. It joins the gateway's neighbour table with its DHCP leases. Each device has mac,
ip, iface, ssid, hostname, state, and ipSource: arp for a live neighbour entry,
lease for a DHCP lease with no live entry.
# What can I shape?
curl -sk https://gateway.example:10443/v1/devices
# Degrade one device, leave another alone
curl -sk -X POST https://gateway.example:10443/v1/shape -H 'Content-Type: application/json' \
-d '{"shapes":[{"ip":"192.0.2.10","latencyMs":150,"jitterMs":30,"mbit":1.5}]}'
# Back to normal
curl -sk -X DELETE https://gateway.example:10443/v1/shapeMeasured 2026-09-11 over HTTPS from a wired Mac on the main LAN, a new TLS connection per call:
| HTTPS round-trip, p50 | 22 ms |
| HTTPS round-trip, max | 43 ms |
| Server-side apply | ~6–15 ms |
Inside tc |
~5–13 ms |
Comfortably inside a 100 ms budget, so an agent can sweep conditions in a tight loop. The qdisc
tree is built once at startup with 32 pre-made slots; a shape change is a tc class change
plus a tc qdisc change, plus a filter when the slot's device changes, all issued in a single
batched tc invocation. No teardown, no rebuild, and changing one device never disturbs another.
Every call that changes shaping (POST /v1/shape, DELETE /v1/shape, POST /v1/reset,
including rejected ones) is recorded with its time, the caller's IP, the shapes it asked for and
what was applied or cleared. The last 500 are served by GET /v1/history; every one is also
written to the gateway's journal as a shape-call JSON line, which survives restarts:
journalctl -u udm-conditioner --no-pager | grep shape-callWhen several agents share the conditioner, this is how to tell who shaped what.
{ "shapes": [ { "ip": "192.0.2.10", "latencyMs": 120, "mbit": 1.5 }, { "ip": "192.0.2.20", "latencyMs": 0, "mbit": 10 } ] }