ISPBox DHCP Device Discovery - Attach CPEs Without Typing MACs

Network > Devices: per-router scan lines, Pending / Ignored / Assigned tabs, and the device table with MAC, IP, hostname, router, interface, first and last seen and the State column

Signing up a DHCP customer used to mean reading a MAC address off a sticker on a roof and typing it into the panel without a typo. Device discovery removes that step: ISPBox watches the DHCP clients your routers see, lists the ones that belong to no service yet, and lets you (or your reseller) attach one to a customer with two clicks. The MAC is never typed.

It lives under Network > Devices, it is part of provisioning rather than monitoring, and it needs no external system.

1. Turning it on per router

The Discover DHCP devices checkbox in the router's API settings, with the explanation that ISPBox reads the lease table every 5 minutes

Discovery is opt-in per router. Open a DHCP-mode router under Settings > Routers and tick Discover DHCP devices. PPPoE routers do not have the option - a PPPoE customer is identified by a login, not a MAC.

What the checkbox does depends on how the router talks to ISPBox:

API + DHCP router - ISPBox reads the router's DHCP lease table every 5 minutes over the RouterOS API.
RADIUS + DHCP router - ISPBox reads the MAC addresses this router asked RADIUS about and got a no for. This needs the MikroTik DHCP server set to use-radius=yes and the ISPBox post-auth columns on the RADIUS server.

A router that serves your guest wifi is deliberately excluded from the RADIUS sweep: rejecting unknown MACs is how guests reach the splash page, not a sign of an unassigned CPE.

2. How the sweep works

Both flavours run every five minutes and both end up in the same list.

The API sweep fans out one job per eligible router - discovery ticked, router active, API mode, DHCP mode, and not already known to be offline. It prints the lease table, then prints the DHCP servers once more to resolve each lease's server to the interface it is bound to, so the list can say which sector or bridge the device appeared on rather than just "somewhere on this router". Older or locked-down RouterOS may refuse that second print; the sweep carries on without it. The job retries three times with a growing backoff and then records the failure on the router.

The RADIUS sweep reads new rows out of the FreeRADIUS post-auth log past a cursor, keeps only Access-Reject rows that look like a MAC authentication (MikroTik MAC auth sends no password, so a genuine one has an empty password or the MAC itself), maps the NAS address back to one of your routers and hands those MACs to the same ingest. It never writes to FreeRADIUS and never changes how anyone authenticates: an unknown MAC stays rejected, and stays on whatever unauthorised addressing the router gives it, until somebody attaches it to a customer.

A lease becomes a candidate only when it is dynamic and was not created by ISPBox (provisioned leases carry an ISPBOX-ID: comment). A MAC that already belongs to any service in your tenant is skipped, and a pending row whose MAC meanwhile lands on a service - because somebody typed it by hand or imported it - is closed automatically and marked assigned by the system. Pending and ignored rows nobody has seen for 30 days are pruned, and the post-auth log is trimmed nightly, so neither table grows without bound.

3. Network > Devices

The page opens on Pending, with Ignored and Assigned beside it and a live count on each. There is a search over MAC, IP and hostname (a MAC term matches in any notation, separators stripped on both sides, and a term that is not MAC-shaped is treated as plain text) and a router filter.

Each row shows the MAC, the lease IP, the hostname the device announced, the router with the interface underneath it and the router's location, when it was first seen and when it was last seen with the lease status as a badge.

The State column is the honest answer to "is this thing there right now":

Online - a sweep saw it in the last 15 minutes. Sweeps run every five, so two missed sweeps plus a little slack is the edge between "here now" and "gone".
Asking for access - the router keeps asking RADIUS about this MAC and keeps getting a no. It is knocking, not connected.
Last seen ... - nobody has seen it recently.
Nothing at all, once the device is assigned. The sweep skips MACs it already knows, so the last-seen stamp freezes at the moment of the attach and would lie about the customer's link. Use the service's own connection state for that.

Above the table, each API router with discovery on gets one line: Last scan: 2 minutes ago - OK, No scan has run yet, or Last scan failed 4 minutes ago: with the reason. That last one matters - a router the sweep cannot reach must not look like a router with nothing new on it. RADIUS routers get no line, because that flavour reads the post-auth log and never talks to the router at all.

Scan now queues a sweep on every discovery router immediately instead of waiting for the next tick.

4. Attaching a device to a customer

Assign device to a client: the device summary with MAC, hostname and router, then a client search with matching customers listed

A pending row offers three actions:

Assign to client - the modal repeats the device, then searches your clients by name, email, phone or client number. Pick one and it lists that client's services that are still waiting for network setup; pick the service and the device is attached. If the client has no such service, the modal links straight to Add service with the device carried along.
New client - opens the Add client form with ?device= so the whole sign-up ends with this device already wired to the new service.
Ignore - parks it under the Ignored tab (your office laptop, a neighbour's phone, a printer). Restore puts it back on Pending.

Attaching writes the service's network credentials and nothing else: the MAC, and an address taken from the router's client pool - the lease IP it already had, when that address is free and inside the pool, otherwise the first free one. If the service has no router yet it gets the one the device was seen on. An API router (or any router with a client pool in ISPBox) with no free address left refuses the attach rather than half-doing it. The claim runs under a row lock and is one-shot, so two people racing for the same CPE cannot both win.

5. What happens on the router

Writing the credentials is bookkeeping; whether the customer comes online depends on where their prepaid clock stands.

The service is active and paid up - ISPBox pushes it immediately. On an API router the MikroTik provisioner applies the setup and the page says "The router has been updated" (or names the error if RouterOS refused). On a RADIUS router the MAC becomes a radcheck identity and FreeRADIUS is reloaded through the ops agent; the device authenticates on its next request. If the reload fails you are told so instead of being promised a customer who is still offline.
The service is a draft or not activated - nothing is pushed. It is provisioned the moment the service is activated and paid for.
At expiry - the prepaid sweep runs every quarter hour and blocks the service through the same enforcer that provisioned it, so the device stops passing traffic on its own. A renewal restores it. The device does not go back onto the pending list: its MAC is now a known identity.

6. The reseller side

The agent portal Devices page on a phone: the no-location hint, a search box, and device cards with MAC, hostname, interface, router, seen times, state and the Attach to customer and Add customer buttons

With the Claim discovered devices toggle in Settings > Agents, the same list reaches your resellers at /agent/devices. This is the flow where a street seller plugs in the customer's CPE, opens their phone and finishes the sign-up on the spot, without your staff ever seeing the MAC.

What an agent sees is narrower than what you see:

Only pending devices - ignoring stays yours.
Only devices on routers at the agent's own location, plus routers you gave no location at all (those count as global, the same rule the service form uses). An agent with no location therefore sees only the location-less routers, and if there are location-bound devices they are missing out on, the page says so out loud instead of sitting silently empty: "Devices on routers tied to a location are not shown because your account has no location - ask the company."

The agent's Attach to customer modal: only customers whose service still waits for network setup are offered

Two buttons per device:

Attach to customer - the dropdown lists only the agent's own customers whose prepaid service is still waiting for network setup. If that customer's clock is already running, the network side is pushed straight away and the agent is told "Device attached - the customer is online"; if it is not, they get "Activate the service to bring the customer online"; if RADIUS did not reload, they are told that too and your office is notified.
Add customer - opens the portal sign-up form with the device attached. The package becomes required (this device has to get one), the connection-point and login fields disappear because the device's own router is the answer, and the client, the prepaid service and the network credentials are created in one transaction.

Claims are one-shot for agents too: the second reseller to tap the same device is told it has already been assigned. The portal home carries a N new devices chip so nobody has to go looking.