Skip to content

Site map

Maps → Site map shows your estate on a real world map - the geographic analog of a floor plan. Every site with coordinates gets a labelled marker (with its device count); devices that carry their own GPS coordinates appear as small dots colored by role. Click a marker for a popup with counts and a jump-off to the site or device page.

What's on the map

  • Sites - labelled markers with a device count and a health ring: the worst monitoring status across the site's device IPs (green/amber/red), so the map doubles as a NOC view.
  • Devices - any device with GPS coordinates, role-colored, with the same health ring. A role can also carry a Lucide icon (set on the role form next to its color) - it shows inside the device's badge on the map, the sidebar, and the floor planner's palette. Camera-ish devices (roles with has FOV) render a field-of-view cone - direction, angle, and reach in meters, or a full PTZ coverage ring - edited with live preview from the sidebar inspector.
  • Free markers - anything else worth pinning (generators, gates, masts): markers typed by your own floor tile types and device roles (zero pre-filled vocabulary), placed by arming a type in the edit sidebar and clicking the map (it stays armed for stamping several). Camera-ish types get cones too.
  • Connections - site-to-site links drawn as arcs, derived from what you already model, never a separate schema:
    • circuits whose A and Z terminations land on two placed sites (colored by circuit type, then status);
    • tunnels, resolved termination → interface → device → site - two sites make an edge, a hub termination makes a star to its spokes;
    • cross-site cables (dark fiber), aggregated per site pair - a bundle is one arc with a count;
    • circuits to a provider network - each to that network's own marker (see Provider networks). Hover thickens an arc and names it with its speed; click opens its popover and the inspector, both showing its link facts - speed, provider, encapsulation, the ports at each end - with jump-offs to both sites and the object. Each kind respects its own view permission.

The layout - the floor planner, on a map

The page is a clone of the floor-plan editor's shell:

  • Header - View / Layout / Cables tabs, the Outline tool in Layout mode (building outlines), New floor plan in Layout mode (a floor plan from the map), a Find on map… search (sites, devices, markers, and outlines by their label or location name - jump + select), Fit to view, the Satellite toggle, the Objects sidebar toggle, and a Display menu in three parts:
    • Layers - Sites, Devices, Links, Cables, Cable routes, Region boundaries, Outlines, Camera FOV cones, and Stack nearby markers. Links are circuits and tunnels; Cables toggles the plain cable lines separately, so a map can show just the carrier picture.
    • Labels - Names (the site and device name chips, and the outlines' labels) and Speed (each line's speed on the line, see Link speed).
    • Color by - Type, Status, Speed or Utilization, for the lines.
  • Left palette rail (Edit mode) - tabbed Sites / Markers, exactly like the plan's palette: click to arm, then click the map. Marker types stay armed so you can stamp several; Esc disarms. Stamping a marker opens a small dialog asking for a name and an optional device link - role markers open the picker pre-filtered to that role. Both are skippable; an unnamed marker displays its linked device's name, then its type name.
  • Right inspector - opens when something is selected. Sites show health, counts, and floor-plan jump-offs; devices show badges, the front image, and the FOV sliders; markers are edited here (label, description, linked device, FOV, delete); links show their endpoints and metadata. Site and device inspectors carry a Details section with the same detail-page rows (and copy buttons) as the popovers - serial, DNS, rack, location, cluster, counts, coordinates, and custom fields - so the answer is on the map either way. A link or a cable shows its link facts, with every link of a bundle. The panel is resizable: drag its left edge (the width is remembered per browser; a small reset button restores the default), and the sliders button in its header picks exactly which detail rows to show - also remembered per browser.
  • Objects - the far-right Objects sidebar, the same one the floor plans and the topology map open: one Search… box over foldable groups - sites by region (a flat list until regions are in use), devices by role (each role headed by its color badge), markers, building Outlines (click one to fit the map to it), links grouped by kind, and a Regions list (regions with a stored boundary; click one to fit the map to it). Click a row to fly to it; Enter in the search box jumps to the first hit. Every site/device row carries its monitoring status pill, a Problems section at the top collects everything down or degraded (worst first), and the All · Down · Degraded · Up tabs under the search box (each with its count, named as your status catalog names the states) filter the whole list. Group headers show down/degraded counts even when folded, and fold state is remembered per browser. On a phone (below 768 px wide) the sidebar starts closed and opens over the map with its own close button, and the header wraps so every toolbar control stays on screen.
  • Hiding part of the map - the eye on a group header takes that group off the map: a device role, or a region's sites. Individual sites have their own eye, since sites are the map's top-level objects and there are rarely many. Roles and regions hide by name, so a device that gets the role tomorrow is hidden too.

    Hiding a site hides everything that belongs to it, not just its pin: its devices, and every circuit, tunnel and cable with an end there - an arc to a hidden site would otherwise hang in the sea. A cable route whose cables are all hidden goes too; a route with no cables is a planned duct and stays. What is left is a map you can actually read.

    Hidden objects stay listed, greyed, so you can bring them back. They drop out of Problems, the triage pill, Find on map, Fit-to-all, the Links and Cable routes lists, and a device's cable count. A "n hidden · Show all" line appears at the top of the sidebar whenever anything is off, and a chip in the map's top-right corner says the same while the sidebar is closed. The choice is remembered per browser. This is finer-grained than Display, which switches whole kinds on and off. The floor plans and the topology map have the same eyes. Keyboard: H hides the selected site, or the selected device's role; Shift+H shows all.

Placed markers are fully editable from the inspector: rename, describe, link/unlink a device, tune FOV, or delete (or press Delete in Edit mode).

The map elsewhere - the Map widget

The same live OSM map (real tiles, your sites/devices, cables, and connection arcs) is reused as a compact MiniMap wherever a map helps:

  • an opt-in Map dashboard widget (Add widget → Map) with an "Open map →" corner link;
  • a collapsible strip above the Circuits table;
  • an "On the map" locator on site and location overviews (the site highlighted; every arc and cable drawn, framed on the site and its direct peers);
  • a Location card on each placed device's page - the device centered, with Site map and Floor plan jump-off buttons.

Markers are clickable everywhere (site → site page, device → device page).

Devices and free markers render as the floor-planner's badge squares (the role/type color, icon or centred dot) rather than plain pins; the selected one gets a primary-colored ring so it's obvious what you clicked.

Deferred (documented, not forgotten)

Multipoint L2VPN / peer-mesh tunnels as mesh overlays, a wireless point-to-point link model, configurable popover fields (the floorplan's registry), and antimeridian-aware arcs.

Popovers

  • Sites - labelled markers with a device count. Click one for a popover with the site page's facts - region, address, time zone, coordinates, and its prefix/VLAN/VM/rack/circuit/contact counts - plus direct links into its floor plans (the map → floor plan drill-down) and a jump to the site page. Copyable values (address, coordinates) carry a copy button.
  • Devices - any device with GPS coordinates: outdoor APs, cameras, gateways, roadside cabinets. Dots are colored by the device's role. The popover shows the configured detail fields first, then the rest of the device page's facts - manufacturer, platform, serial, asset tag, rack and position, location, cluster, OOB IP, interface/IP counts, coordinates - with copy buttons on the copyable ones, and (in edit mode) a Remove from map action. Toggle the Sites / Devices layers in the toolbar.

Placing things

Sites get coordinates two ways:

  • On the map - switch the header tabs to Edit. The palette rail lists sites not yet placed: pick one, click its spot, done. Already-placed pins become draggable. Every change saves immediately (and lands in the change log - you need site.change for what you move).
  • In the form - Site and Device forms both accept decimal-degree Latitude / Longitude, for pasting coordinates from elsewhere.

Devices appear on the map through their coordinates - set them on the device form, stamp a role marker and link the device from the placement dialog, or use the palette's Devices tab: search for any device (the sliders open the advanced filter), then click its spot. Picking an already-placed device moves it. Dragging a placed device or removing it from the map needs device.change.

Danbyte never geocodes addresses - there's no lookup of your street addresses against an external service. You place things yourself.

Chrome and memory

  • Problems pill - when anything on the map is down or degraded, a pill in the top-left corner counts it, one chip per state named as your status catalog names it; each click flies to the next problem, worst first, and opens its popover.
  • Legend - bottom-left, folded to a Legend chip by default; explains pins, badges, cluster chips, the health ring's states (named as your status catalog names them) and the line colors, as Color by draws them: the kinds, the statuses on the lines as their pills, or the speed tiers on the lines. Its ✕ (Hide legend) folds it again.
  • Fullscreen - the expand button in the toolbar puts just the map fullscreen; every control keeps working.
  • A metric scale bar sits bottom-left.
  • The map remembers where you were: the last view (center + zoom) and the layer toggles persist per browser, like the satellite, labels, FOV and Color by choices. Fit to view is always one click to see everything again.

Site colors and icons

Every site can carry a marker color and a Lucide icon, set on the site form (Marker color / Marker icon, next to the coordinates). The map pin takes the color and shows the icon inside it; with nothing set, the pin is the theme color with a standard building glyph. The same pair exists on locations - there they color the location's badge on list and detail pages, and a location's outline when its type has no color. A location with neither takes its type's.

To color many at once, tick them in the Sites, Regions or Locations list and choose Edit in the bar that appears: sites and locations take a marker color and icon, regions a color. Leave a field unticked to keep each one's own; tick it with nothing picked to clear it.

Close markers cluster

In View mode, markers that would collide collapse into a round chip with a count. Its border takes the dominant site color inside; a corner dot carries the worst monitoring status among the clustered objects, so a pile can never hide a problem. Click a chip to zoom into it - at maximum zoom, markers on the same coordinates fan out ("spiderfy") so each one is clickable. Picking a clustered object from the sidebar, search, or a ?focus= link zooms and fans automatically until that marker is visible.

Stacking is a preference: Display → Stack nearby markers (default on). Turned off, nothing collapses - crowded markers shrink instead, down to about half size, so every site stays individually visible and clickable. The choice applies to the mini maps too.

Edit and Cables modes never cluster - dragging, click-to-place and route drawing work on the flat markers exactly as before. The MiniMap (the dashboard widget, site/device locators, circuits strip) clusters too, with a smaller chip.

Name chips declutter with zoom as well: site names appear once you're reasonably close, device names closer still, and hovering or selecting a marker always shows its name at any zoom. Display → Labels → Names (remembered per browser) switches to hover/selection-only if you prefer a bare map.

What draws a line between two sites

Site-to-site links are derived, never modelled - there is no "connection" object to create. A line appears when one of these resolves to two different sites that are both placed on the map:

Line What has to be true
Circuit Both the A and Z termination land on a site, and the two sites differ. Cabling a side to a port is not required for the line - it ties the circuit to the port. A side on a VM interface names that VM at its end.
Circuit to a provider network One end lands on a placed site, the other on a provider network: the line runs from the site to the network's marker (see Provider networks). Cabling is not required here either.
Tunnel Each tunnel termination resolves to a site: a device interface through its device, a VM interface through its VM (its own site, else its cluster's, else its host's). Two sites draw one line; a hub termination draws one line per spoke. A peer mesh of more than two sites is not drawn.
Cable Its two ends sit on devices at different sites. Cables between sites are aggregated per site pair, so a bundle is one line.

A site is placed once it has a latitude and longitude - an unplaced site drops every line that would touch it. If a link you expect is missing, check that end's site first.

Provider networks

A provider network - the MPLS cloud or carrier fabric your circuits' far ends land on - has no place of its own, so the map gives it one: a marker (a neutral rounded square with a cloud, its name and how many circuits reach it) at the centre of the placed sites it serves. When that point lands on or next to one of them - a network serving one site, or sites in a ring round it - it moves north, by a quarter of the spread of its sites and at least 0.05°; two networks serving the same sites step apart eastwards. Each circuit from a site to the network is its own line, styled like the other circuit lines (its circuit type's colour, then its status's), so several sites on one MPLS service draw as hub and spoke.

Click the marker for its panel: the provider, the service ID, and every circuit with its site, type, commit rate and status - a circuit jumps to its line. Display → Layers → Provider networks (on by default, remembered per browser) turns the markers and their lines off together; in the Objects sidebar each network has its own eye, and the n hidden chip counts the ones you hid. A network goes when every site it serves is hidden, and a line with its site. The dashboard and site-page mini maps leave these lines out.

You see a network and its lines only with view on circuits and on provider networks, and only for the circuits whose site end is at a site you may view: a reader scoped to some sites never sees a marker built from circuits at the others, and its place is worked out from their sites alone.

Dependencies

Display → Layers → Dependencies (off by default, remembered per browser; offered only with view on device dependencies) draws the device dependencies over the map:

  • Between two devices with their own coordinates: a straight line from the upstream to the downstream device.
  • Every other dependency between two placed sites: one bowed line per site pair, medium and kind, from the upstreams' site to the dependents' site, bowing the other way from the circuit and tunnel arcs. Hover lists the first device pairs and how many there are.

Each line wears its medium's colour and line style, with a chevron pointing downstream; a peer link has none. A dependency inside one site whose devices have no coordinates of their own draws nothing. A hidden site or device takes its lines with it. You see a line only for the dependencies you may view between devices you may view.

A line shows how fast it is whenever Danbyte can work that out from what you have recorded: a circuit's commit rate or its terminations' port speeds, a tunnel's own Capacity (set on the tunnel), the speed of the interfaces at a cable's ends. Circuits → Link speed on the site map has the rules and which one wins. When nothing is known a line has no figure - never a guess.

Color by

Display → Color by picks what a line's color means:

Color by A line's color
Type (default) Its kind: circuits sky, tunnels violet, cables amber - unless the object brings its own color (a circuit type's, a cable's).
Status Its status's color, from your status catalog. A line with no status is grey.
Speed The speed tier of its figure, on the scale the topology and the port faceplates use. A line of unknown speed is grey.
Utilization Live traffic, one direction per half - see Utilization.

The legend follows: the kinds under Type, the statuses on the map's lines as their pills under Status, the speed tiers on its lines under Speed, the utilization bands and the time of the newest sample under Utilization. The choice is remembered per browser.

Utilization

Color by → Utilization shows how busy each line is right now. A line is split at its midpoint: the half at one end shows the traffic leaving that end, so A → Z is drawn on A's half and Z → A on Z's. Each half takes its band's colour and width:

Band
< 10 % sky, thinnest
10–25 % emerald
25–50 % lime
50–75 % yellow
75–90 % orange
≥ 90 % red, widest
No data grey
  • Traffic comes from the interfaces at the line's ends: the rate between the last two SNMP counter samples of each port, what leaves one end or, failing that, what arrives at the other. A bundle adds up its links.
  • Utilization is that traffic over the line's speed, falling back to the ports' reported speed when the line has none.
  • No data means no end of the line is an interface with two recent samples: the device was never polled, polled once, or its last poll is more than two hours old (three poll intervals, when the tenant's scheduled polling runs less often). Tunnels to a virtual machine have no data.
  • Direction chips on each half give the figure - 42%, or the rate where no speed is known - with an arrow along the half. They are placed like the speed labels, which they replace while Utilization is on.
  • Hovering a line names both directions; the legend carries As of, the time of the newest sample.
  • The rates refresh every minute while Utilization is on and are only read then. Interfaces you may not view count as no data.

Keeping the figures current needs polling: turn on Poll devices every under MAC tracking, or poll by hand.

Changed in 0.17

A cable with no color of its own was drawn in the circuits' sky blue while the legend called cables amber. It is amber now, on this map and in the Map widget and the locators.

Speed labels

Display → Labels → Speed (on by default) writes each line's figure on the line: 10G, 100/20M (down/up), 2×10G for a bundle. To keep the map readable:

  • only lines in view are labelled, at most 300 at a time;
  • nothing is labelled from far out (the world, a continent);
  • a line gets its label once it is long enough on screen to carry one, so zooming in brings the shorter lines' labels in;
  • labels never overlap - the longer line keeps its label;
  • cables drawn on top of one another (between devices with no coordinates of their own, every cable of a site pair runs from one site's point to the other's) share one label, added up the way a bundle is;
  • while a trace lights some cables, only those keep their labels.

A line of unknown speed carries no label. The choice is remembered per browser.

A line's popover and its inspector show the same facts:

  • Speed - the figure and where it came from: 100G · commit rate, 500/100M · port speed, 10G · interfaces, 1G · set on tunnel, 10G · cable; Unknown when nothing is known.
  • Bundle - for a line of several links, how many there are and how many have no known speed: 4 links · 3 unknown.
  • Provider, Circuit ID (with a copy button) and Type for a circuit; Encapsulation and Group for a tunnel; Cables for a site pair's cables.
  • Ends - for a single link, the device and port at each end with the port's speed. A circuit side that is not cabled shows its termination's port speed.
  • Links - for a bundle, each link's speed and its two ends. The popover lists the first three and the inspector every link the map has (the first 50); both count the rest as +N more.

An end on a device you may not view reads Restricted and says nothing more. Clicking a cable opens its popover and the inspector too; a cable into patch panels shows its own ends above the ports its strands come out on.

Cabling on the map

Every cable whose two ends land on the map draws as a line - you don't need to draw a route first. A cable follows its route's geometry if it has one, otherwise it's a gentle dashed curve between the two devices (bundles fan out so you can tell them apart).

Click a device to open its inspector:

  • Cabling lists every end-to-end run through the device (panels and splitters crossed). The ⤳ trace button on a run lights that whole path on the map and fits the view; clicking any cable line toggles its highlight.
  • Ports lists the device's interfaces and front/rear ports, each showing a colored dot when cabled or a + Connect when empty. Connect opens the cable form seeded with that port as the A-side - the fastest way to wire fibre straight from the map; the new cable appears the instant you save.

The device popover shows a cable count and a Trace shortcut.

Cables mode - routes for the outside plant

The header's Cables tab (editors only) is the floor planner's tray editor, geographic. Draw a route by clicking waypoints along the duct / aerial / trench path (double-click or Enter to finish, Esc to cancel), name it, then assign the physical cables right in the naming dialog (pick a cable and the line you drew IS that cable's path - no duct required; the name and color prefill from it) or later from the route inspector. Reshape any time: drag a vertex, click a segment's + to add a bend, right-click a vertex to remove it.

Routes render in every mode as faint channels (toggle under Display → Cable routes); their assigned cables draw as thin colored lines inside the channel, routed through the route graph between their endpoint sites. A cable bundle whose members all follow real routes drops its abstract arc. Cable detail pages gain Show on site map (/site-map?trace=<cableId>) once the cable is routed. Routes are a registered RBAC type (cableroute) - users without the grant see no plant geography. A route lists only the cables you may view (hidden_cable_count counts the others); assigning or removing a cable needs change on that cable, and saving a route's cables keeps the ones you cannot see.

For splice closures and PON splitters, see fibre.

Building outlines

A campus is more than pins: draw each building's footprint on the map and link it to the location it is. An outline is a filled polygon with a label; clicking it opens what is inside.

Draw one - switch to Layout and click Outline in the header. Click the building's corners, then double-click or press Enter to finish (Esc cancels). A small dialog asks for the site (the nearest site you may edit is picked), the location and an optional label, and creates it. The + beside the Location picker makes a new location at that site there and then - typed Building when your location types have one.

Reshape and edit - in Layout mode, click an outline to select it: drag a point to move it, click a side's + to add a point, right-click a point to remove it (three always stay) - the same moves as a cable route. The inspector on the right links the location (the locations of the outline's site, as their color badges), sets a label, a color of its own, and Locked - a locked outline shows no handles, so it can't be moved by accident. Del removes the selected outline. An outline that would cross itself is refused.

What it shows:

Comes from
Color The outline's own color, else its location's type color, else the location's color, else neutral grey.
Label The outline's own label, else the location's code (A1), else its name. Shown with Display → Labels → Names; with Names off, on hover and selection only.

Drill down - in View mode, hovering an outline lights it up; clicking it opens its panel: the location's type and code, how many sub-locations, rooms, racks and devices are in it and under it (those you may view), and its floor plans - the floor plans of the location and of the locations inside it, then the site's site-wide plans. Open floor plan opens the ground level of the location's own floor plan (else of the site-wide one): the floor at elevation 0, else the lowest one that is not a basement. Open location opens its page. An outline's Opens (in its inspector, from any floor plan, snapshot or live view you may view) replaces that: Open floor plan then opens the plan it names - unless you may not view it, when the location's ground level stays.

Outlines are listed in the Objects sidebar and found by Find on map, by label, location name or code. Display → Layers → Outlines hides them all; hiding a site in the sidebar hides its outlines too.

Permissions - outlines are their own type, Site-map outlines (sitemapoutline), scoped to their site like devices and audited in the change log. Site roles include them. An outline linked to a location you may not view is not shown to you at all - not its shape, not its label; linking one needs view on the location, and the location must be at the outline's site.

New floor plan from this view

A campus plan can start from the map: in Layout mode, New floor plan in the header (needs permission to add floor plans) lets you frame the area - drag a rectangle over it, or press Enter for the whole view (Esc cancels). A dialog asks for:

Name The floor plan's name; it must be unique among the site's site-wide floor plans.
Site The site whose outlines and pins are in the framed area, else pick one.
Cell size 1 m by default. Raised when the area would need more than 2,048 cells across; the line under the fields shows the grid and its size in metres.
Background Map or Satellite, from the tile servers set under Map tiles.

Create draws the framed area from the tiles into one image, in your browser, at the map's zoom (lowered when the image would be over 8,192 pixels a side), with the tile attribution in its bottom-right corner. It makes a site-wide floor plan of that size at true scale with the image as its background, copies the site's building outlines inside the area onto it as areas linked to the same locations, and opens it. See Plans made from the Site map for the scale, the attribution and the areas.

When the tiles can't be read - on an isolated network, or from a tile server that does not allow pages to read its tiles - the dialog says so and offers Create without background: the same plan with the outlines and no image. Reading tiles needs the tile server to send Access-Control-Allow-Origin (OpenStreetMap's and Esri's do); for a self-hosted tile server, add the header there. Danbyte's server never fetches tiles for this either.

Floor plan footprints

A floor plan made from the map keeps the box it spans. The map draws each one you may view as a faint dashed rectangle, named on hover (the floor plan and the floor); a click opens the plan. The levels of an aligned floor plan share one box and are drawn once: named after the floor plan, listing its levels on hover, and opening its ground level. Display → Layers → Floor plans turns them on and off. A plan whose box was expanded shows its new box. Plans of sites hidden in the sidebar are hidden with them.

Placing a site from its address

Besides dragging a pin in Layout mode or typing coordinates, the site form can geocode the Address line. Type an address and leave the field: while the coordinate fields are empty, the best match fills them automatically (a toast names the place it chose). Find on OSM next to the field does the same on demand and lists the candidates, for when the automatic match picks the wrong one - and coordinates you typed yourself are never overwritten. Candidates are named in your browser's language, or English when it sends none, rather than each place's local language. Powered by OpenStreetMap's Nominatim, one lookup per action, © OpenStreetMap contributors.

Region boundaries

Regions that carry an OpenStreetMap boundary shade their outline under the markers, tinted by the region's map color (muted zinc when no color is set). The polygons are decoration, not controls - clicks pass straight through to pins and the map. Toggle them under Display → Region boundaries (remembered per browser, like the other layers). Boundary data © OpenStreetMap contributors, ODbL.

Satellite view

The header's Satellite button swaps the basemap to imagery - Esri World Imagery by default (their attribution shown as required). The choice is remembered per browser. A deployment can point the satellite basemap elsewhere in Settings → Site map → Map tiles (satellite URL + attribution), same rules as the street tiles: https-only, {z}/{x}/{y} placeholders, and the tile host must be allowed in the nginx CSP img-src (the shipped config already allows server.arcgisonline.com). If a basemap's tiles are CSP-blocked, the map shows a banner linking back to this page instead of failing silently.

Map tiles - read this before heavy use

The map background is raster tiles from a tile server. By default that is OpenStreetMap's standard tile service, which is donated, donation-funded infrastructure with a strict tile usage policy. Danbyte follows it:

  • the required attribution (© OpenStreetMap contributors) is always shown on the map and is never hidden - leave it alone; it's a condition of use;
  • a Report a map issue link is included, as the policy recommends;
  • tiles are browser-cached per their HTTP headers, never bulk-downloaded;
  • the browser sends a valid (origin-only) Referer with tile requests.

The default is fine for light internal use - a handful of operators looking at a map. If your deployment is large, busy, or public-facing, the policy expects you to use your own tile source: set Settings → Site map → Map tiles to any raster tile server (an https://…/{z}/{x}/{y}.png template) - a commercial provider, or self-hosted tiles. Set the matching attribution string; nearly every provider requires one.

Content-Security-Policy

The bundled nginx config allows images from tile.openstreetmap.org (street map) and server.arcgisonline.com (the default satellite imagery). If you configure a different tile server for either basemap, add its origin to the img-src directive in /etc/nginx/sites-available/danbyte.conf (see the CSP line) and reload nginx - otherwise the browser blocks the tiles and the map shows a warning banner over a plain gray background.

Upgrading an existing install: re-running the bundle's install.sh regenerates the nginx config with the current CSP automatically. The in-app updater can't edit nginx - after an in-app update, add whichever hosts are missing by hand (safe to re-run; it only adds what's absent):

CONF=/etc/nginx/sites-available/danbyte.conf
for host in https://tile.openstreetmap.org https://server.arcgisonline.com; do
  grep -q "$host" "$CONF" || \
    sudo sed -i "s|img-src 'self' data: blob:|img-src 'self' data: blob: $host|" "$CONF"
done
sudo nginx -t && sudo systemctl reload nginx

Airgapped servers

Tiles are fetched by the browser, never by the Danbyte server - so an airgapped server is a non-issue: operators whose workstations have internet access see the full map. Only when the workstations themselves can't reach a tile server (a fully isolated network) does the map fall back to a plain background - markers, placement, and popups still work. For real tiles there, self-host a tile server on the isolated network and point the Map tiles setting at it. A floor plan made from the map is drawn from the same tiles in the browser too.

Vector basemap and label language

Raster tiles carry their labels baked into the image, in the local language - a site in Dubai shows Arabic street names only. A vector basemap sends the map data instead, and the browser draws it, so it can pick the language of the labels.

Settings → Site map → Basemap:

Setting Meaning
Basemap Vector tiles or Raster tiles (the Map tiles card below). A new install starts on vector; an upgraded install keeps raster until you switch.
Vector source A TileJSON in the Shortbread schema, or a full MapLibre style URL, https only. Blank uses the OpenStreetMap Foundation's Shortbread vector tiles (https://vector.openstreetmap.org/shortbread_v1/tilejson.json).
Attribution Shown on the map. Blank uses the OpenStreetMap credit.
Label language The default: English, Local, Browser language, or English / browser language and local - e.g. Sheikh Zayed Rd (شارع الشيخ زايد).

Each user can change the label language under Preferences → Site map (Auto follows the deployment default). A label takes the feature's name_<language> and falls back to its local name when it has none; Browser language tries each of the browser's languages in order.

How it is drawn:

  • The style, the label font (Inter, the app's own font) and everything else ship with Danbyte. Only the tile host is contacted. The style is muted like the rest of the app, with its own light and dark variant.
  • Every overlay (pins, clusters, cables, arcs, outlines, field-of-view cones, plan footprints) stays as it was, on top of the basemap. The mini maps use the same basemap.
  • Satellite stays imagery; with a vector basemap it gets the vector labels on top, in the same language.
  • A browser without WebGL, or one that can't reach the vector tiles, falls back to the raster tiles with a small note in the corner of the map.
  • A floor plan made from the map draws its background from the vector tiles too, rendered once in the browser.
  • The code loads only when a map with a vector basemap opens.

A third-party style URL is used as it is, with its name labels switched to the chosen language. Its own glyph and sprite hosts then need the CSP below as well. A TileJSON that is not in the Shortbread schema draws nothing; give a style URL for it instead.

The OpenStreetMap Foundation's vector tiles have their own usage policy: the attribution stays on the map, and the browser only fetches the tiles it shows. For heavy, public or offline use, point Vector source at your own Shortbread tile server (for example tiles made with Tilemaker and served over https).

Content-Security-Policy

Vector tiles are fetched with fetch, not as images, so the tile host goes in connect-src, and MapLibre needs worker-src 'self' blob:. The shipped nginx config allows https://vector.openstreetmap.org. For a different vector source, add its host to connect-src in /etc/nginx/sites-available/danbyte.conf and reload nginx. If the tiles are blocked, the map says so and falls back to raster tiles. Upgrading: the 0.20 post-upgrade step updates the CSP (Upgrading).

API

GET /api/site-map/ returns the effective tile config plus the RBAC-scoped sites (all of them - unplaced ones carry null coordinates so the edit panel can offer them) and every device with coordinates. Site coordinates are plain fields on the Site resource (latitude / longitude, decimal degrees), so they're scriptable like everything else.

Building outlines are /api/site-map-outlines/ (?site=, ?location=): points is a list of 3 to 500 [lat, lng] pairs (not closed - the last point joins the first; a repeated closing point is dropped), with site_id, location_id, label, color, z, locked and opens_id (a floor plan of the tenant you may view; null clears it). Each row also carries display_label and display_color, as the map draws them, and opens (id, name, stack_name, kind) - null with opens_hidden when you may not view it. GET /api/site-map-outlines/<id>/drilldown/ returns the panel's counts, floor plans (each with first_floor_id, its ground level) and open_floor_id (the outline's Opens target when it has one you may view, else the first plan's ground level).

POST /api/floor-plans/from-map/ makes a floor plan from a box of the map; see its API. plan_footprints in GET /api/site-map/ lists the floor plans with a geo anchor that you may view: {id, name, stack, site_id, bbox, levels}, bbox being [south, west, north, east]. An aligned floor plan is one entry: id is its ground level, name the floor plan's and levels its floors' names, lowest first; any other floor is an entry of its own, with levels holding its name.

GET /api/site-map/cables/ returns every cable with two placeable ends. An end carries the point it draws at, its device_id and its site_id - a device with no coordinates of its own is drawn at its site's point, and that device is not in the payload above, so the site is what identifies it.

GET /api/site-map/connections/ returns the lines between sites - circuits, tunnels and each site pair's cables, as What draws a line between two sites describes. Each kind needs its own view permission, and both sites must be ones you can view.

It also returns provider_networks: each provider network a placed site's circuit reaches, {id, name, service_id, provider: {id, name}, latitude, longitude, site_ids, circuits: [{id, cid, site: {id, name}, type, status, color, commit_rate_kbps}]}, latitude/longitude being where the map places it. The line of each such circuit is in connections as a circuit whose site_z is the network's marker - {id: "pn:<network id>", name, latitude, longitude} - and which carries provider_network: {id, name}; with ?include=capacity its network end has site_id: null. A circuit needs circuit.view, its network providernetwork.view and its site site.view. The query count does not grow with the number of circuits.

Permissions

Everything on the map is what you may view, each kind by its own grant and site scope:

  • Sites count only the devices and floor plans you may view, and list only those floor plans.
  • Markers are the ones the marker list shows you (sitemarker, by its device's site). A marker whose device you may not view keeps its place, label and type but reads device: null and device_hidden: true on the map, and {"id": null, "name": "Hidden", "hidden": true} in /api/site-markers/.
  • Cables are the ones /api/cables/ lists you: the cable grant's constraints and sites apply, not just having the grant. A cable line needs both ends on devices you may view; a cable bundle between two sites, its link facts and its speed are made only of cables you may view, and so is a circuit's walk to the ports it is cabled to. A route lists only the cables you may view.
  • Circuits and tunnels follow their own view grants. An end on a device or VM you may not view reads restricted with no device or port.

Dependencies: ?include=dependencies

/api/site-map/connections/ takes ?include=dependencies (with capacity: ?include=capacity,dependencies) and then also returns dependencies, the Dependencies layer's lines:

kind Fields
devices id (dep:<dependency id>), dependency_kind (dependency or peer), medium ({id, name, slug, color, text_color, icon, line_style} or null), redundancy_group, and a (upstream) / z (downstream) as {lat, lng, device_id, device_name, site_id}.
sites id, dependency_kind, medium, site_a (the upstreams' site) / site_z, count, and pairs: the first 20 {upstream: {id, name}, downstream: {id, name}, redundancy_group}. A peer pair's sites are sorted.

Only rows you may view (devicedependency.view) between devices you may view, between sites you may view; without the grant the list is empty.

Both line endpoints take ?include=capacity, and each line then also carries:

Field What it holds
capacity The line's speed: kbps, up_kbps (only when the other direction differs), label (10G, 100/20M, 2×10G), source, and count / unknown - how many of its links have a known speed and how many do not. null when no speed is known: never a guess.
links The end-to-end links the figure is made of, the first 50: each with its a and z end, its own capacity and the cable_id that carries it (null for a circuit or tunnel).
link_count How many links there are in all.

Without it the payloads are as before. The map widget and the site and device locators share these endpoints and don't ask, so they pay nothing for it.

Live traffic: GET /api/monitoring/interfaces/live/

?ids=<id>,<id>,… - up to 500 interface ids - answers {as_of, interfaces: {id: rate | null}}. A rate is in_bps, out_bps (each null when that counter went backwards), speed_mbps, at (the newer sample) and interval_s (between the two samples); as_of is the newest at. Null means no live rate (see Utilization). An id from another tenant, or one you may not view, is left out. The figures come from monitoring/iface_live.py, which anything else showing live port traffic should read.

source names where the figure came from - the rules, and which one wins, are under Circuits → Link speed on the site map:

source Line The figure
commit circuit its commit rate
port circuit the slower termination's port speed, with the upstream speed where it differs
interface circuit the slower of the interfaces its sides are cabled to
override tunnel the tunnel's own capacity
cable cable per link, the lower of its two end interfaces' speeds; a line with several links adds them up

A cable into a patch panel is followed through the panels to where its strands come out. A trunk between two panels carries one link per strand patched at both ends - a duplex connector's two strands are one link - and a strand that stops dark inside a panel carries none. A cable with several ports on each end carries one link per position: its first A port with its first B port, the second with the second, in the order they were added - so two ports to two ports are two links, and extra ports on the longer end carry none. A cable with one port on an end is a breakout: that port links to every port on the other end. A site pair's line adds up every link its cables carry, each once; a cable that carries no link at all counts as one of unknown speed.

An end names its site_id, the device - or for a tunnel the virtual_machine - and the port it lands on, with the port's kind and, for an interface, its speed_kbps. A circuit's ends carry their termination too: its side, port speed and upstream speed. What you see follows your permissions:

  • a device or virtual machine is named only when you can view it; otherwise the end reads restricted: true and carries nothing else;
  • a circuit's ends are traced to what they are cabled to only when you can view cables;
  • a speed read off interfaces makes a link's figure only when you can view the devices at both of its ends - otherwise the link counts as unknown.

The figures cost the same number of queries however many links the map draws.