Network Map

A geographic map of every device the appliance has seen, with clustering at low zoom, individual markers at high zoom, and a status filter for blocked, throttled, monitored, and healthy devices. Includes a historical timeline mode for replaying status at a past hour.

The Network Map turns the device list into a map view. Devices are pinned to their last-known geographic location and coloured by status. Zoom out to see clustered hotspots; zoom in to see individual markers. Click any marker to open a side panel with the device summary, and from there jump straight to its details.

When the Map Is Available

The map needs two independent things: a base map (the geography you see) and device locations (the dots drawn on top). The map page tells you honestly which of the two is present, so you always know what to do next.

There are three states you may encounter:

1. No base map installed

If no map tile data is installed on the appliance, the page shows an explanatory message describing what the map does and noting that a map tile pack must be installed. You do not see a blank or black map — just a calm message pointing you at the fix.

To make the map appear, install a map tile pack on the appliance (see Installing Map Tile Data below). The map becomes available shortly after the pack is installed.

2. Base map present, but no device locations yet

Once a tile pack is installed, the geography renders and you can pan and zoom freely. If the appliance has not yet resolved any device positions, the map shows the geography with no device dots and a banner appears at the top:

Device locations unavailable — location service not running

The map is fully usable in this state — only the device dots are missing. To get device dots, ask the administrator to confirm the location service is running and pointed at a working location source in config.yaml.

3. Full live map

When both the base map and device locations are present, you see the complete live map: the geography fills the browser window, device markers are drawn and coloured by status, the status filter pills sit along the top-left, and a legend sits in the bottom-left.

Installing Map Tile Data

The base map (the geography under the device dots) is supplied by separate map tile packs that an administrator installs on the appliance. The packs are independent of the appliance software, so the map can be updated on its own schedule.

Map tile data ships as its own set of packages:

dhcp-dpi-map-shapes — the base shapes pack: the world base map and country borders. Install this first; every country builds on top of it.
Per-country packs — one package per country, for example dhcp-dpi-map-pl for Poland and dhcp-dpi-map-de for Germany. More countries are added over time as additional packs.

Installing a pack adds its tiles to the appliance and the map becomes available shortly afterwards — the install reloads the map tile server automatically, so no manual restart is needed. To update tiles later, install the newer version of the pack.

If you have no base map yet, the map page shows the “no base map installed” message described above until a pack is installed. Once dhcp-dpi-map-shapes and at least one country pack are in place, the geography renders; device dots additionally need a working location service.

Layout

+-----------------------------------------------------------+
| [All] [Blocked] [Throttled] [Tracked] [Monitored] [Healthy]   <- Status filter
|                                                           |
|                                                           |
|                                                           |
|                  GEOGRAPHIC MAP                           |
|                  (zoom + pan + markers)                   |
|                                                +-------+  |
|                                                | Device |
|                                                | Panel  |  <- slides in on marker click
|                                                +-------+  |
|                                                           |
| +---------+                                       [Home]  |
| | Legend  |                              <- bottom-right  |
| +---------+                                               |
+-----------------------------------------------------------+
|  Clock toggle (top-right corner of the map) opens         |
|  the historical timeline bar shown above.                 |
+-----------------------------------------------------------+

Map Interaction

The map behaves like any modern web map: drag to pan, scroll to zoom, two-finger pinch to zoom on touch.

Pan — click-and-drag the background.
Zoom — scroll wheel, the on-map + / - controls (top right), or pinch.
Home button — bottom-right of the map. Returns the view to the default centre and zoom level (configured by the administrator).
Theme — the map style automatically tracks the GUI theme. In dark mode you get a dark tile style; in light mode a bright style.

Markers and Clustering

The map switches between cluster markers and individual device markers based on zoom level.

Cluster Markers (low zoom)

When zoomed out, devices in the same area are bundled into a single cluster marker. The cluster is drawn as a small donut chart, sized by how many devices it contains and segmented by status:

A cluster with 50 devices where 10 are blocked and 40 are healthy shows a donut with a red slice and a green slice in those proportions.
The total count is printed in the centre of the donut.

Clicking a cluster marker zooms the map in by two levels, centred on the cluster — repeated clicks drill all the way down to individual devices.

Individual Device Markers (high zoom)

At zoom level 15 and higher, clusters dissolve into individual markers, one per device. Each marker is a coloured circle whose colour matches the device status (see legend below).

Clicking an individual marker opens the Device Panel on the right side of the screen with that device’s summary.

Tip. Donut clusters with a single colour mean every device in that area shares the same status. A cluster with three or more big slices is a hotspot worth investigating — for example, a cluster that is half red and half amber probably contains a misbehaving subnet.

Status Filter

The pill bar at the top-left scopes the map to a single status.

Filter	What you see
All	Every located device on the map
Blocked	Devices currently blocked at the firewall
Throttled	Devices currently rate-limited
Tracked	Devices currently in the kernel rate-limit tracking set
Monitored	Devices placed under monitoring by an operator, automation rule, or the LLM
Healthy	Devices with no active enforcement

The filter applies to clusters and to individual markers. When a filter other than All is active, clusters lose their multi-colour donut breakdown — every device inside them already shares the selected status.

The filter does not affect what the location lookup produces, only what is drawn on the map. Devices the appliance has never resolved to a location stay off the map regardless of filter.

Legend

The legend in the bottom-left of the map shows what each status colour means.

Colour	Status
Red	Blocked
Amber	Throttled
Slate grey	Tracked (kernel rate-limit set)
Brand blue	Monitored
Green	Healthy

In historical timeline mode the legend changes to “Historical Status” and adds a caveat: tracked devices come from the kernel rate-limit table, which is not stored over time, so historical views never show tracked entries — affected devices appear dimmed.

Device Panel

Click a device marker to open a 350-pixel side panel on the right.

The panel shows:

MAC Address — the device identity (monospace).
Hostname — last advertised hostname, or Unknown.
Status — coloured pill badge matching the marker.
City — best-effort city name from the location service, or Unknown.
Last Seen — relative time since the most recent event, formatted as “5 minutes ago” or “3 hours ago”.
View Device Details — a button at the bottom that opens the full Device Details (chapter 14) page for this device.

Press Escape or click the X in the panel header to close it. Clicking on empty map space also closes the panel.

Historical Mode

The clock icon in the top-right of the map opens a timeline bar that lets you replay device status for any past date and hour.

Click the small clock button (just below the navigation controls) to expand the timeline bar across the bottom of the map. The bar contains:

Clock pill — currently open. Click to return to live mode.
Date picker — choose any date the appliance has records for.
24 hour blocks — one per hour of the chosen day. Block height/opacity reflects the event volume in that hour, so you can quickly spot busy stretches. Click an hour block to load device status for that hour.

The map redraws using the historical status of every device at the chosen hour. Returning to live mode (click the active clock pill) restores the live view.

Limitation. Tracked-device status comes from the kernel rate-limit table, which is only kept in memory. Historical mode therefore only shows blocked, throttled, monitored, and allowed states — entries that were merely tracked at a past time are not recoverable. Affected entries are dimmed in the legend.

How Devices Are Located

The map uses a location service running alongside the appliance. The appliance does not do its own IP-to-location lookup or installed-license-key trickery — it asks the configured service.

For each MAC the appliance has seen, the location service returns a latitude, longitude, city name, and street address (if available). The appliance caches the result and uses it to position the marker.

What this means in practice:

The lookup is per MAC, not per IP. Two devices sharing an IP (NAT-ed) still get separate map entries based on their MAC.
A device with no location result is not drawn on the map. It still appears everywhere else (Dashboard, Devices History, Device Details) — it is simply not pinned.
The marker position is the last resolved location. If a device roams, the map position reflects the most recent successful resolution.
City and address come from the same service. They appear on the device panel and the Network Map’s clustering uses them to group nearby devices.

The appliance does not transmit any device data outside the local network to populate the map — the location service runs on infrastructure you control.

Drilling In

The map is one of several entry points to a single device. Once you have found something worth investigating, follow it through.

Goal	Where to go
See the device’s full event history, IP assignments, and enforcement state	Device Details (chapter 14), via the Device Panel button
See every device the appliance has ever seen, not just the located ones	Devices History (chapter 13)
Apply an enforcement action	Use the action buttons on the Device Details page
Inspect alarms that fired for this device	Alarms (chapter 11)

Performance Notes

The map debounces viewport changes by about 300 ms and limits per-request data volume.

When you pan or zoom rapidly, the map waits for the motion to settle before fetching new data. This avoids hammering the appliance with hundreds of small queries. A spinner appears in the top-right while a request is in flight.

The single-device view (zoom 15 and higher) caps results at a few hundred markers per viewport. If a city has more devices than that, zoom in further to drill down — the cluster view always shows totals, even when the individual view is capped.

Devices History (chapter 13) — the full device list, including devices that have no map location.
Device Details (chapter 14) — the page that opens when you click “View Device Details” in the Device Panel.