Device catalog¶
Before you add devices, it helps to define the catalog they draw from: who makes the hardware, what models exist, and how you classify devices. You build this once and reuse it across every device.
There are five catalog objects, each with its own sidebar page:
| Object | Answers | Example |
|---|---|---|
| Manufacturer | Who makes it? | Cisco, Juniper, Dell |
| Device type | What model is it? | Catalyst 9300-48P |
| Device role | What job does it do? | Access switch, core, firewall |
| Platform | What OS does it run? | IOS-XE, JunOS, PAN-OS |
| Platform group | What OS family is that? | Windows, Linux, network NOS |
Manufacturers¶
The vendor. Create a manufacturer with a name (and optional URL and description) before - or while - creating its device types.
Can't delete a manufacturer?
A manufacturer can't be deleted while device types still reference it. Remove or reassign those device types first. The delete dialog tells you when this is the case.
Device types¶
A device type is the reusable hardware template - "a Catalyst 9300-48P is 1U tall, made by Cisco, model C9300-48P." Every device of that model points at the same type, so you describe the hardware once.
Fields:
- Manufacturer, model, part number
- Platform - optional default OS for devices of this type. A device without a platform of its own inherits it - see effective platform
- Height (U) - how many rack units it occupies
- Rack width - full (default) or half, for gear like a Mellanox SN2010 where two units mount side-by-side in one U (see half-width devices)
- Full depth - occupies both rack faces (default). Shallow gear unticks this and frees the opposite face in rack elevations. A change to the height, width or full depth that would put a racked device of the type over another or past the top of its rack is refused, naming the devices.
- Airflow, weight - hardware facts (airflow also exists per device as
an override). The airflow directions - front to rear, rear to front, left
to right, right to left, passive, mixed - are the
airflowlist ofGET /api/dcim/choices/, the list the forms offer and the library import accepts; the type's page shows it in the Hardware card. - Cooling - how the hardware is cooled: air, liquid, hybrid or immersion
(
cooling_method; blank reads as air). A device of the type takes it unless it sets its own, and a rack's cooling capability is checked against it - see Cooling. - Heat output (W) - the heat the hardware gives off, where that is not its
allocated draw (
heat_output_w): a rack counts it in place of the device's draw when it adds up its heat. Blank counts the draw. Cooling and heat output sit in the form's Chassis card and the page's Hardware card. - Size (mm) - the body's width, height and depth, in tenths of a millimetre. Drawings scale the hardware by it, and it sizes the type's devices on floor plans: a free plan places a device at its width × depth (True size), and the 3D room stands one with no model as a box of that size. A device can carry its own size over the type's (Size).
- DIN rail - the rail profiles the type mounts on (TS 35, TS 15, G 32) and the rail's position: its centreline below the body's top edge, the middle when left empty. A type with a profile needs its width and height. See mounting devices.
- Icon - a Lucide icon (
icon, e.g.router,network,shield) that devices of the type draw with on floor plans when zoomed out. It wins over the role's icon; a device can set its own over it. Blank uses the role's. The type's page shows it in the Hardware card. See Icons when zoomed out. - Description, tags, custom fields
Device types accept custom fields (target Device types) - handy for catalog-level attributes such as a warranty window or an end-of-life date that belongs to the model, not the individual device.
Picking an icon¶
The role, device type and device forms share one icon picker: a search
box over every Lucide icon, with a Network group at the top - router,
switch, firewall, server, access point, camera, printer, phone, UPS and
power, PDU, storage, patch panel, load balancer, VPN, cloud and monitor.
The group's icons are found by what they stand for too: type firewall or
ups. Clear sets it back to blank. Nothing is pre-filled; every icon is
optional.
Importing from the NetBox devicetype-library¶
You rarely have to type a hardware model in by hand. The community devicetype-library (public domain) holds thousands of ready-made definitions, and Danbyte's component templates use the same taxonomy - so they import 1:1. Click Import from library on the Device types page and either:
- paste GitHub links to
.yamlfiles in the library (one per line - regularbloblinks work, they're converted automatically), - paste a folder link - a
/tree/URL such as…/device-types/Cisco- to import every device type in it (one manufacturer at a time; the importer lists the folder over the GitHub API and pulls each file), - paste the YAML itself, or
- upload the
.yamlfiles.
The whole device-types folder is thousands of files - too many for one
synchronous import, so pull it a manufacturer (or a few) at a time.
Manufacturers are created as needed. Everything Danbyte models - interfaces,
console/console-server ports, power ports/outlets, front/rear ports,
module bays, device bays (+ subdevice role, exclude-from-utilisation),
inventory items, plus full-depth, airflow, and weight - comes across, and
the library's elevation images are downloaded automatically when the file
declares them. The library has no cooling key, so a device type arrives
without a cooling method or heat output. Module-type files (module-types/…) and rack-type
files (rack-types/…) import through the same dialog - auto-detected, so a
mixed paste works; the keys a rack-type file may carry, Danbyte's own
max_power_w, cooling_capability and cooling_capacity_w among them, are
listed under Rack types. The Module types and Rack types pages open the same
dialog from the same Import from library button, right after
Import / Export on all three pages (CSV round-trips live in that menu).
Every construct in the library schema now maps - anything unrecognised in
a file would still be reported, never silently dropped.
Each file needs add on what it creates: a device-type file needs add on device types, a module-type file on module types, a rack-type file on rack types. A file you can't add is reported as refused and the rest of the batch goes on. A folder import checks the same when it runs in the background.
Stackable switches: the upstream library has no stack-position concept, so
its port names are literal (GigabitEthernet1/0/1).
Tick Stackable during import and Danbyte rewrites the leading slot digit
to the {position} token
(1/… → {position}/…, Juniper-style 0/… → {position:0}/…) so one
imported type serves every member of a stack.
Server without internet access? Tick Fetch with my browser. The links
you pasted - single files or a whole /tree/ folder - are downloaded by your
browser (GitHub allows that cross-origin) and the YAML text is sent to Danbyte,
exactly as if you had pasted it; the server never contacts GitHub. The tick is
remembered per browser. It needs the reverse proxy's Content-Security-Policy to
allow raw.githubusercontent.com and api.github.com in connect-src - the
shipped nginx template does; a hand-written config must add them.
Filtering a long catalog¶
Import a vendor folder or two and the catalog runs to hundreds of models, so the Device types list carries a full filter rail. The search box still matches name and model; the rail narrows by:
| Facet | Picks out |
|---|---|
| Manufacturer | one vendor's models |
| U | a height range - 1U top-of-rack gear, or everything ≥ 4U |
| Images | whether the type has a rack-face photo at all |
| Faceplate | how its devices draw their panel: Photo ports, Custom or Auto |
| Usage | In use vs Unused - catalog entries no device is built from |
| Lifecycle | vendor lifecycle state - what's end-of-life |
| Scope | site-local vs tenant-wide entries, where the deployment scopes catalogs per site |
| Tags | any tag; the chips in the Tags column toggle the same filter |
Facets stack (Cisco + Unused + End of life is the prune list), and the count chip beside the title always reports what survived them. A facet that can't split the rows you have - every type global, nothing laid out yet - hides itself rather than take up rail space.
Two columns carry what the rail filters on. Images shows which faces exist
(Front, Rear, or -), and Faceplate reads Photo ports when
markers are placed on a photo, Custom when a
faceplate layout is saved, and a muted Auto when the
panel is drawn automatically - so Images: Yes plus Faceplate: Auto is
exactly the queue of types you have a photo for but haven't marked up yet. Hide
either column from the Columns menu if you don't work with panels; the
filters stay.
Deleting types in bulk¶
Tick the checkbox on any row and a bar appears at the bottom of the list with
the selection count, Export (CSV / Excel / JSON of just those rows) and
Delete. The selection is drawn from the rows the rail is currently showing,
so the usual prune - Cisco + Unused + End of life, select all,
delete - clears a vendor's dead models in one pass. The bar only appears if you
hold delete on device types.
The confirm names up to five of the types and, crucially, sums the devices
attached to the whole selection: "12 devices use these types - they'll keep
working but lose their type reference." Deleting a type never deletes its
devices; Device.device_type is nulled, so those devices keep running,
untyped, until you point them at another type. What does go with the type is
its own component templates, faceplate and photo-port
markers.
Deletion runs through POST /api/device-types/bulk-delete/ ({ids}) and
returns {"deleted": n} - a count of types, not of the templates that
cascaded with them. The bar sends 100 types per call, one call after another -
a library's worth of templates in one request outruns the request timeout -
and the button counts the calls (Deleting… 3 / 8). A call that fails stops
the run and the message says how many types went; the rest stay selected (see
Large selections). The
submitted ids are re-checked server-side against your
tenant and, where the deployment scopes catalogs per site, your site scope: an
id you can see but not write (a tenant-wide entry, or one local to another
site) is skipped rather than deleted, so n can be smaller than the number you
selected. Every removal lands in the change log.
Rack-face images¶
On a device type's detail page you can upload a front image and a rear image of the hardware. These get painted onto the device wherever it appears in a rack elevation, with the device name overlaid - so a rack diagram looks like the real thing. Use the Front / Rear toggle on the rack to switch faces. The same images also render read-only on each device's Overview tab, so you can see the hardware without opening the type.
Uploads are downscaled server-side to at most 2000 px on the longest edge - aspect ratio preserved, EXIF rotation applied - so a raw phone photo doesn't ship megabytes to every rack view. Library-fetched images get the same treatment, and so do image attachments.
Every upload also loses its metadata - the GPS position, the camera and its
serial, XMP and IPTC data, comments - because device type photos are served
without a login. A photo that carries none is stored exactly as uploaded,
whatever its format. A re-saved animated GIF, WebP or APNG keeps every frame
with its timing, loop count and disposal, and a lossless WebP stays lossless.
0.17.0-dev3 kept the metadata of photos under 2000 px; manage.py
strip_photo_metadata (with --dry-run to list them first) re-saves the
photos stored since without it. It removes an old file only once the new one
has been read back clean with all its frames, and reports any photo it
kept instead.
Recovering lost images¶
Images live in the media folder; the device types live in the database. Lose
the media folder - disk corruption, a restore that skipped media/, a botched
migration between hosts - and every type still lists an image it no longer
has. Reimport images on the Device types page (needs change on device
types) rebuilds exactly that: it matches your existing types against a
devicetype-library-layout repository and re-downloads their elevation images.
Nothing is created, renamed, or otherwise modified - only the two image fields
are written, and every write lands in the change log.
Point it at a repository in whichever form you have handy - plain
owner/name, a github.com URL (optionally /tree/<ref>), or a full https
base such as an internal mirror. The default is Danbyte's
device-library fork, which
keeps the upstream layout: images at
elevation-images/<Manufacturer>/<slug>.front|rear.png. Matching reuses the
import's own naming: the slug embedded in a surviving image filename first
(it's still in the database even when the file is gone), then
vendor-prefixed slugs derived from the type's name, part number and model.
Dry run classifies without writing: matched (the repo has images for
it), no match, or has images (both faces present and their files
actually exist on disk). Apply is fill-gaps-only by default - a face is
written only when its field is empty or the field is set but the file is
missing from storage. That second case is the whole point: after media loss
the database still says "has image", and Danbyte treats it as a gap rather
than trusting the stale reference. Tick overwrite to replace intact
images too, e.g. after switching to a repo with better photos. A repo that's
unreachable mid-run marks the affected faces fetch failed and carries on -
one bad fetch never aborts the batch.
Small catalogs answer synchronously with a per-type report; anything over
~50 types runs in the background with the same pollable progress as the
folder import. The API is
POST /api/device-types/reimport-images/ ({"repo": …}, flags ?dry_run=1
/ ?overwrite=1), which either returns the report or 202 + a run to poll
at import-runs/<id>/.
Airgapped deployments (update checks disabled) get a clean refusal instead of a hanging timeout - no outbound request is attempted. Recovery there is the offline route: restore the media folder from a backup, or re-upload images per type, or import bundles exported with Include photos, which carry the files themselves.
3D models¶
A device type can carry a 3D model of the hardware. The 3D room view draws every device of the type that stands on the floor with it, fitted to the hardware's size. A device can have its own model, which wins over its type's.
A type with a model shows it on its Overview in a 3D model viewer at the top of the right-hand column. The model stands the way the room stands it, front toward you. Drag to orbit and scroll to zoom; the toolbar has Front, Rear and Top views, Fit, Ports (the mapped ports, in one neutral colour - a type has no port state; hovering one names it) and Fullscreen. The type's rack-face photos stay in their own section below the cards.
The 3D model card manages it - Upload / Replace and Remove, then:
| Setting | What it does |
|---|---|
| Size | Fit to size (the default) scales the model to the device's width, height and depth where they are recorded - its own (Size), else the type's - else to the footprint of the tile it stands on, so a model fills its tile. Give the type a width, height or depth to size it exactly. Scaling is uniform, by the tightest axis, so nothing is squashed. Own size draws it at its own size in metres. |
| Up axis | Y up (glTF's convention) or Z up (most CAD exports). |
| Front | The model axis its front faces: +Z (glTF's convention), −Z, +X or −X. The room turns that face to the tile's front edge. |
Uploading, replacing and removing need change on the type; anyone who can view the type sees the card read-only. Each change lands in the type's change log.
What can be uploaded¶
The upload dialog takes .glb, .gltf (self-contained), .step / .stp, .iges / .igs, .stl and .obj. Everything is converted in the browser and stored as one binary glTF (.glb) - the only format the server keeps:
- STEP and IGES go through OpenCascade (compiled to WebAssembly, shipped with Danbyte and loaded only when a CAD file is picked - nothing is fetched from the internet, so it works airgapped). It runs in the background, so a large assembly doesn't freeze the page. Part and face colours in the STEP file are kept; parts without one are a neutral grey.
- STL and OBJ go through three.js's own readers, in a neutral grey (an OBJ's
.mtlmaterials aren't carried). - A
.gltfthat refers to separate.binor texture files is refused - upload the.glbinstead. - Native CAD files (
.sldprt,.ipt,.f3d, …) can't be read: export them as STEP or STL first.
Before saving, the dialog shows the converted model with its triangle count, stored size and dimensions, and lets you set:
- Units - mm, cm, m or in. STEP and IGES default to mm; STL and OBJ carry no unit, so a part more than 10 units across is taken as mm, a smaller one as metres. If the dimensions look a thousand times off, change this.
- Up axis - STEP, IGES and STL default to Z up, glTF and OBJ to Y up.
The saved file is always metres and Y up, with parts merged per material so a 400-part assembly draws as a handful of meshes. A model over 300,000 triangles can't be saved as it is; Simplify reduces it to the cap (with meshoptimizer's simplifier, also shipped with Danbyte).
Using models from GrabCAD¶
GrabCAD models are mostly native CAD files plus STEP, IGES or STL exports.
- On the model's GrabCAD page, download the STEP (
.step/.stp) file if there is one, else the STL. A native file (SolidWorks, Inventor, Fusion) won't load - Danbyte says Export it from GrabCAD as STEP or STL. - Unzip it if it came as a
.zip, and upload the.stepor.stlon the type's 3D model card. - Check the dimensions under the preview. If they are wrong by a factor of 10, 25.4 or 1000, pick the right Units; if the model lies on its side, switch the Up axis.
- Save. If it faces the wrong way in the room, set Front on the card.
Format rules¶
The server checks every upload, whichever way it arrives:
- the file starts with the binary glTF header (
glTF), says version 2, and its declared length equals its size; - it is at most 25 MB - set by
DEVICE_MODEL_MAX_BYTES; - every buffer and image is inside the file (the binary chunk, a buffer view,
or a
data:URI). A model can't refer to anything outside itself, so it can't make a viewer's browser fetch from elsewhere. The one data-less buffer allowed is a meshopt fallback buffer, whichgltfpack -cwrites and the room never reads; - any extension it requires is one the room reads without a decoder from
elsewhere: the
KHR_materials_*family,KHR_texture_transform,KHR_mesh_quantization,KHR_lights_punctual,EXT_meshopt_compression,EXT_mesh_gpu_instancing,EXT_texture_webpandEXT_texture_avif. Draco (KHR_draco_mesh_compression) and Basis textures are refused. A meshopt-compressed model is decoded by bundled WebAssembly, which the page policy allows with'wasm-unsafe-eval'(Hardening → Content-Security-Policy).
The file is stored under the media folder but never served from /media/:
only through the type's (or device's) model/ endpoint, to a signed-in user
who may view it, as a download (model/gltf-binary, nosniff, attachment).
API¶
| Call | Does |
|---|---|
GET /api/device-types/{id}/model/ |
Downloads the model (view on the type). |
POST /api/device-types/{id}/model/ |
Sets or replaces it: multipart file, optional fit (auto / native), up (y / z), front (+z / -z / +x / -x). Change on the type. Answers the type. |
DELETE /api/device-types/{id}/model/ |
Removes it (change on the type). |
The type's model_3d is the model's download URL (never a file path), or
null; model_3d_fit, model_3d_up and model_3d_front are plain fields you
can PATCH. The spreadsheet export carries the three settings; the file
itself is never imported or exported. Library bundles and the NetBox
library import don't carry models.
Jumping to the devices¶
The Devices count on a device type's detail page is a link: it opens the Devices table pre-filtered to that type (the Type facet is seeded from the URL), so you land on exactly those devices - the same foreign-key linkage used throughout Danbyte to keep related objects one click apart.
Share a device type as a bundle¶
Teaching Danbyte a piece of hardware is real work: stamp the component templates, draw the faceplate, place the photo-port markers on the rear image, find the vendor OID that reports drive health. All of it is knowledge about the model - identical for everyone who owns that box.
A bundle is that work in one file. On a device type, Export ▸ Bundle downloads everything that makes the model work:
- the type's own fields - height, width, depth, airflow, cooling method and heat output, weight, DIN rails
- every component template (interfaces, console, power, cooling, panel ports,
bays) - cooling under the keys
cooling_intakesandcooling_outflows, an outflow naming itsintake - the faceplate layout and the photo-port markers
- the front and rear photos, when you tick Include photos
- inventory-item templates (the disk bays a chassis ships with)
- the custom SNMP sensors bound to it
Import bundle on the device-type list reads one back. It previews first - importing a file from elsewhere should never be blind - showing what would be created, and only then offering to apply it.
Three rules make a bundle safe to accept from anyone:
- No credentials. Sensors poll with your deployment's own SNMP profile; a bundle references nothing secret.
- Imported sensors are observe-only. Whatever the file says, they arrive as
drift- they surface differences for review and can never overwrite a status you set. Switch one to automatic yourself if you want that. - Nothing is overwritten silently. A device type you already have is skipped unless you tick Update the device type if it already exists (which needs change access, not just add).
- The same rules as the form. The type's fields - sizes between 1 and 5000 mm, a DIN rail on the body, a body size for DIN-rail types, choices, the faceplate - and every component template and sensor are checked as the API checks them, and on a replace the type's devices on DIN rails and in racks must still fit. A file that breaks one is refused whole with the field at fault, and nothing of it is saved. The preview checks the type's own fields already.
Ids never travel - manufacturers, an outlet's inlet, a front port's rear port all move as names and are re-resolved locally. Anything that can't be resolved is reported, never dropped in silence. Photo-port coordinates are normalized 0–1, so they line up at any resolution of the same photo; if the bundle was built against an image you don't have, the import says so - upload it on the device type and the markers land correctly.
Photos in a bundle¶
A type with photos asks on Export ▸ Bundle whether to include them; the box is ticked. The photos travel inside the file as base64, so the far side gets the same pictures the markers and the calibration were placed on. Without them a bundle is a small text file you can read and diff.
- Caps. 3 MB per photo and 6 MB per bundle, decoded. A stored photo is at most 2000 px on its long edge, so most fit; one that doesn't is left out of the export with a warning and travels as a reference.
- Checked by content. On import each photo must be a JPEG, PNG, GIF or WebP when its bytes are read, and match the type the bundle states. A photo that fails, or a bundle over a cap, is refused whole with the photo named. The preview checks the photos too.
- Stored as an upload. Imported photos go through the same path as an upload on the device type: downscaled to 2000 px, metadata stripped, animation kept. The bundle's photo ports and calibration come along unchanged.
- Replace. With Update the device type if it already exists, a bundle that carries a photo replaces that photo; one that doesn't leaves the stored photos alone. A replaced photo without photo ports in the bundle loses its old calibration, as on an upload.
The format stays version 1. In the file, images.front and images.rear are
true or false when the photo is only referenced, or
{"mime", "filename", "data"} when it is carried. Bundles from earlier versions import as before,
and an earlier version reads a photo bundle as one that references its photos.
API: GET /api/device-types/{id}/library-export/?include_photos=1 and
POST /api/device-types/import-bundle/?dry_run=1&replace=1. The API leaves
photos out unless asked, so existing scripts get the same file. The import
report lists the photos a bundle carries in images.
Component templates¶
A device type owns component templates - the ports the hardware ships with: interfaces, console port(s), power inlets, PDU outlets, and patch-panel rear/front ports. When you create a device of the type, Danbyte stamps every template into a real component on the device, so a "C9300-48P" arrives with its 48 interfaces, console port, and two PSU inlets already in place - no hand-typing ports per device.
Manage them on the device type's Components tab, which splits the component
kinds - Interfaces, Console ports, Console server ports, Power ports, Power
outlets, Cooling intakes, Cooling outflows, Rear ports, Front ports,
Aux ports, and Services - into
sub-tabs with counts. The open sub-tab is part of the URL
(?tab=components&sub=power-port), so you can link someone straight at one
kind, and reload or back/forward without losing your place.
Device bay, module bay, inventory item, antenna and cooling templates have no
type; their API endpoints neither take nor return one, and ignore a type
sent anyway (before 0.20, adding a device bay template failed with a server
error).
Aux ports are the catch-all for connectors the other kinds don't cover: USB
(A/B/C/mini/micro), video outputs (HDMI, VGA, DVI, DisplayPort), SD/microSD
slots, RJ11, audio jacks, grounding lugs, and RF connectors (RP-SMA, SMA,
N-type, MMCX, U.FL, QMA, 4.3-10) - so a device type can model everything on
its panel, including the coax run from an AP to its external antenna. Template names support
two shorthands: a [1-24] range creates one template per port in a single
add ([01-24] keeps the zero padding; front-port templates take consecutive
rear positions), and a {position} token resolves to the device's stack member number
when components are stamped (and renames ports when a device changes stack
position) - see virtual chassis.
Tick rows to reveal a bulk bar with Edit, Rename, Clone, and
Delete:
- Rename - find/replace across the selected templates' names (optional
regex), with a live before→after preview. Ideal for renumbering a bank of
ports (
Gi→GigabitEthernet,1/0/→2/0/). It refuses names that would collide, and takes at most 1000 rows at a time, as Clone does. Photo-port markers, faceplate slots, and the placed ports on existing devices follow the rename, exactly as a single rename does - a marker left on an old name would otherwise read as a port the type still has, and syncing a device would stamp it a second time as a bare component. - Clone - duplicate the selected templates, applying a find/replace so the
copies get new names (e.g. clone
1/0/*to2/0/*for a second line card); with no find/replace the copies get a “ copy” suffix. The same bulk bar (and actions) works on a real device's Interfaces too.
Notes:
- Materialisation happens on device create (and skips any name the device already has, so imports that pre-create ports are safe). Existing devices are not retro-modified when you edit templates - but each device has a Sync from type button (see below) to back-fill the changes on demand.
- Power outlet templates can reference the power inlet template that feeds them; front-port templates map onto rear-port template positions - the same relationships the concrete components carry.
- Cooling intake and cooling outflow templates carry a connector, diameter and max flow; an outflow template can name the intake template that feeds it, as a CDU's do. They have no faceplate marker. See Cooling.
- Service templates (name · ports per protocol) stamp a Service onto each new device; tick Monitor and those services are watched from the moment the device has an IP - fleet-wide service monitoring configured in one place. See service monitoring.
Sync an existing device to its type¶
Editing a device type's templates doesn't touch devices that already exist. To push the changes onto one, open the device and pick More ▸ Sync from type (top- right). It opens a preview first - no changes until you confirm:
- Add (safe, always applied on confirm) - components the type defines that the device is missing (e.g. interfaces added to the type after the device was built). Shown as green chips.
- Not in type (amber chips) - components on the device with no matching template: hand-added ports, SNMP-discovered interfaces, or components dropped from the type. These are kept by default.
- Tick Also remove the components not defined by the type to delete those extras. This is destructive - it cascades their cabling and IP assignments - so the dialog turns the affected chips red and warns when any interface being removed carries IPs. The button becomes a red Sync & remove extras.
- Interfaces of an installed module belong to the module, not the type: they are never listed as extras and never removed by a sync.
Faceplate slots and photo markers count as expectations too: a port drawn on the layout that no template defines still shows under Add, and confirming stamps it as a bare component (type "other") for you to refine - so a marked port never points at nothing after a sync. Front-port markers are the one exception (they need a rear-port mapping a marker can't express) and are left as ghosts on the render.
Sync is name-based (it never renames or retypes existing components) and needs
device.change.
Antennas¶
Antennas are pure L1 on a lot of APs, and this is where they document. Two situations, two shapes:
- Integrated antennas (most indoor APs) are components on the device - how many, what kind, what gain. Nothing to cable. Add antenna templates to the device type and every AP built from it carries its elements; or add them per device on the Hardware tab.
- External antennas - a sector on a mast, a dish on a wall - are their own small device: give it a device type whose antenna component describes the radiating element and whose aux port carries an RF connector type. The coax run AP → antenna is then an ordinary cable between two RF aux ports, with placement, faceplates and tracing for free. Create an "Antenna" device role for them with the quick-add on the device form if you want one - roles stay yours to define.
An antenna records its type (omni, directional, sector, patch, yagi, parabolic, internal), gain (numeric dBi), bands (a picked list - 2.⅘/6/60 GHz, sub-1 GHz, cellular; multi-band is simply several), polarization, connector, and a direct mount flag for elements screwed straight onto the device's connector with no cable run - so they don't fall between "integrated" and "external". Gain and bands are structured on purpose: a future coverage view can consume them without a re-model.
Antennas are never cable endpoints themselves - the aux port is the cable end - but photo markers can place them on a device image like hardware parts.
Sync the whole fleet at once¶
When a template change affects every device of a model, Sync devices on the
device type page does the same job across the fleet instead of one device at
a time. It appears once the type has devices and needs device.change.
It previews first, like the per-device flow: how many devices would change, and a per-device count of what would be added or is extra. Also remove components this type no longer defines is the same destructive option, and the dialog names how many of those extras carry IP addresses before you tick it.
Pressing Sync shows a confirmation naming how many devices are about to change - and, when removal is ticked, that components and their cabling are about to be deleted and cannot be recovered. Confirming queues a background run - a type with hundreds of devices is not something to hold a browser request open for - and the dialog follows its progress. When it finishes it reports how many devices changed, how many were skipped (your grants don't cover them), and any that failed.
Permissions are re-checked per device
Being allowed to sync the type is not the same as being allowed to change every device built from it - a site-scoped grant may cover some and not others. The job re-checks each device as it goes and skips the ones you can't change, rather than trusting the check made when you pressed the button.
- Per the zero-pre-filled-data rule, no templates ship - but the type/connector dropdowns follow the standard taxonomies, so imported device-type definitions carry over.
Faceplate builder¶
Every device draws its front panel at true physical scale - connector cages are sized from the real form-factor dimensions (an SFP28 cage renders narrower than the QSFP28 beside it; an RJ45 jack is taller than both), laid out on an EIA-310-proportioned 1U bar. With no configuration, Danbyte lays the panel out automatically: ports group by slot, split where the media type changes, fill two rows belly-to-belly (odd on top), and bank in twelves - the way real 1U hardware is built.
When the automatic layout isn't how your hardware looks, open the device type's Faceplate tab and build it yourself. The canvas is the panel - the same true-scale drawing devices render, with every cage draggable:
- Toggle between the Front and Rear sides - each is its own layout, and a port lives on exactly one of them.
- Drag templates from the palette (all eight component kinds - interfaces, console, power, aux, panel ports) onto the panel; reorder by dragging, drop onto the dashed + zone to start a new group, double-click a cage to remove it.
- Drag a module bay from the palette to drop a placeholder where the
bay physically sits. On a device, the installed module's faceplate composes
into that spot (
{module}resolves to the bay position); an empty bay shows a labelled placeholder cage. A bay you don't place still appends its module at the end, as before - so old layouts keep working. - Click a group to edit its label, rows (1–4), and banking (visual gaps every N ports) in the toolbar, or add blank cages and silk-screen label text.
- On a multi-U device the panel splits into one lane per rack unit; the toolbar's U control picks a group's unit. Set U tall to have a group span several units - the lanes it covers merge into one taller canvas (no separate + zone), handy for devices whose ports don't line up on U boundaries.
- Save stores the layout on the device type - every device of the type
(including each member of a virtual chassis;
{position}names resolve per member) renders it, and devices with a rear side get a Front / Rear toggle on their panel. Reset to auto deletes it.
Templates renamed or deleted after a layout was saved render as dashed ghost cages, and the tab counts them so you can tidy up. Interfaces the layout doesn't place are appended automatically - nothing silently disappears.
Photo ports (anchoring ports on a real image)¶
When a device type has a front and/or rear image, a
Photo ports tab appears. Instead of the schematic cage layout, you place
port markers directly on the photo - drag an interface (or console / power
/ panel port) template from the palette onto the image, then position it
precisely: drag it, grab the corner handle to resize, nudge with the arrow
keys (Shift = coarser), or type exact X / Y / W / H percentages. A
fine-grid snap keeps rows aligned. Coordinates are stored normalized
(0–1), so they scale to any render size. Markers reference their template by
name, and renaming a template follows into them (and into custom faceplate
slots) automatically - a placed port never orphans on rename. On the device
side each port carries a frozen marker identity (stamped from the template
at creation), so renaming a device's own port - Port 1 → X1-P1 - keeps its
placed marker resolving too; hovers then show the real name.
A special device can override the type's layout entirely: the device page grows a Photo ports tab (when the type has an image) whose palette lists that device's real components and whose Save writes a device-only layout - Reset to type layout returns to inheritance.
Bulk place lays a whole run at once: pick the kind and a from/to port range, set rows, numbering direction and optional bank gaps, then anchor the grid - type the corner percentages or click Set first/last port on photo. Amber ghosts preview every marker live before you commit. The range spans all ports of the kind, so an already-placed run can be re-laid too: opening Bulk place on a fully placed side seeds the grid from where the run sits now, and the header counts how many markers a placement would overwrite.
What the port hover card shows is configurable deployment-wide under
Settings → Component details: an ordered field list (name, type, state,
far end, VLAN, live SNMP facts, IPs, description, MAC, MTU, LAG, tags -
defaults to the first seven). Far end names the device and port at the
other end of the port's cable (→ sw-2:Gi1/0/1); on a rack's elevation it
shows only when that device is one you can view. A field with no value on
that port simply doesn't render, so a rich list costs nothing on sparse
interfaces. The same list applies to the schematic and the photo faceplate
alike, on the device page and on the
rack's elevation. A list an admin
saved before Far end existed keeps its own fields; add Far end to it there.
Once a type has an image and at least one placed marker, its devices show the photo faceplate in place of the schematic one - each marker matched to the device's real interface by name (so it carries the same state colour, live SNMP dot, hover card and link), and the markers also render on the device's face in the 3D room view. Hover. A photo port's hover card shows the same rows as the drawn faceplate's - name and printed label, type, state, far end, VLAN (native / trunk), live SNMP state, IPs - in the order set under Settings → Component details. A power, console, aux or panel-port marker shows its kind and type, whether it is cabled, and - when that list includes Far end - what its cable reaches.
Size. By default the photo draws at its upload size (its own pixels, never wider than the pane). Tick Use this size everywhere in the editor and its Fit / − / + zoom is saved with the layout for that side: Fit keeps the photo inside the pane, a percentage draws it at that fraction of its natural pixels - and the device page's photo panel follows. The topology Diagram draws photos at rack width unless the device, its type or its role sets Topology photo size to Own size; then it uses this saved size, else the upload size (see Photo nodes).
Calibration. A photo can also say how big it really is: two guides at
known points across it - its edges, or any two features a known distance
apart - with the real distance between them, and where the DIN rail runs
across it. That gives the photo's true width in millimetres, which
cabinet drawings and the Diagram's Own size draw it at.
Calibrate in the photo editor shows the two guides (on the photo's edges
to start) and the dashed rail line: drag them, or nudge the focused one with
the arrow keys (Shift for bigger steps), and type the Distance (mm)
between the guides - the type's width to start. The rail band is drawn at
the true height of the type's first DIN profile, and the editor reads out the
photo's size (Photo 60.0 × 146.5 mm). Clear calibration removes it;
zooming while calibrating only magnifies. A device can carry a calibration of
its own - its photo editor shows the type's, marked From type, until the
device changes it; without one it uses its type's.
Replacing or clearing a photo drops that side's calibration; resizing it keeps
it. In the API it is image_ports.view.<side>.cal = {left, right, span_mm,
rail}: the guides as fractions of the photo's width, the distance between
them in mm, and the rail's centreline as a fraction of the photo's height (or
null). A device's own image_ports is checked the same way as its type's.
Types without photo ports keep using the schematic faceplate builder above.
The palette also offers the type's inventory-item templates under Hardware - place disk bays, PSUs and other parts on the photo the same way. Hardware markers resolve to the device's real parts by name and are coloured by the part's status (a Failed disk reads red on the faceplate and in 3D); hovering shows the part's media, capacity, speed, status and serial. The status can be set right there - see part status. Hardware markers never join the cable-connect flow.
Module bay templates are placeable too, under Module bays (line cards) - mark where a chassis's card slots physically are. Because a slot is a broad rectangle rather than a connector-sized sliver, a dropped bay marker starts at 20 % × 45 % instead of the port default; resize it from there like any other marker.
A bay marker answers one question - is this slot free? - so it is drawn as occupancy, not speed and not health: a bay with a module seated in it is filled, an empty one is the same faint outline an idle port wears. Hovering (2D) or clicking (3D) names the installed module type and its serial, or reads Empty. On a device type there is no device yet, so every bay draws as empty - that is the honest answer, not an error. The key under the panel lists only the occupancies actually on screen, and only when the panel carries bay markers at all. Bays are informational here too; install and remove modules on the device's Hardware tab.
Note the split with the schematic faceplate builder, which stays port-only: there a bay is a group placeholder whose installed module's own faceplate gets composed in, while the photo builder marks the slot's real position on the artwork.
Mapping ports on a 3D model¶
A type with a 3D model can carry its ports on the model the way photo ports carry them on a photo. The 3D room then draws each mapped port on the model, coloured by its state, and cables end at the port instead of the middle of the box.
Map ports on the type's 3D model card opens the editor: the model large on the left, the type's interface, front/rear port, console and power templates on the right, grouped by kind, with a search box and a mapped count per kind.
- Place a port. Pick it in the list and click the model. The marker lands where you clicked, facing out of the surface there, and the next unmapped port is picked, so a run of ports is one click each. Next unmapped (or Enter) skips ahead.
- Move or clear. Drag a marker over the surface to move it. Pick a port and press Backspace (or Clear) to take its marker off.
- Row. Switch to Row, place the row's first port, then its last (Gi1/0/1, then Gi1/0/24): the ports between fill in evenly, each dropped onto the surface. 2 rows lays the common switch layout - odd ports on the first port's row, even ports on the last's, one column per pair; 1 row spaces them on the line between the two.
- Copy from photo ports. Starts from the type's photo ports: the front photo's markers project onto the model's front, the rear photo's onto its back, each dropped onto the surface, ready to adjust. Ports already mapped stay where they are.
- Undo / redo (Ctrl+Z / Ctrl+Shift+Z) work inside the dialog. Nothing is written until Save, which sends the whole mapping in one request. If someone saved a mapping since you opened the editor, Save is refused and says so rather than overwrite it.
A port is stored at its spot in the model's upright bounding box - after the Up axis and Front that stand it in the room - as fractions 0..1 of each side, with the outward direction of the surface there. That survives the room fitting the model to any size. Changing the model's Up axis or Front turns its mapping with it, so each port stays on the same spot.
Replacing the model clears its mapping, since the ports were placed on the old shape. When the new model has the old one's proportions (within 5% on each side), the upload dialog offers Keep port mappings, ticked. Removing the model clears the mapping too.
Markers name templates by kind and name, as photo ports do, so a device's
ports match by name, case and spacing tolerant, with {position} rendered
for a stack member. A device that draws its type's model uses its type's
mapping; Map ports on the device's own card saves a mapping for that
device only (starting from a copy of the type's, listing the device's real
components), and Use type's ports goes back to the type's. A device with
its own model has its own mapping or none.
Mapping needs change on the type (or the device); anyone who can view it
sees the mapped count. Each save lands in the change log. The mapping is the
model_ports field - {bounds, ports: [{kind, name, p, n}]}, p the 0..1
spot, n the unit normal, bounds the upright size it was made on - and the
spreadsheet export carries it as a JSON column, checked on import like any
other field.
| Call | Does |
|---|---|
GET /api/device-types/{id}/model-ports/ |
The mapping and its version (view on the type). |
PUT /api/device-types/{id}/model-ports/ |
{version, model_ports} replaces the whole mapping; null clears it. A stale version answers 409. Change on the type. |
GET /api/devices/{id}/model-ports/ |
The device's own mapping, its version, and the effective one it draws with its source (own / type). |
PUT /api/devices/{id}/model-ports/ |
Saves the device's own mapping; null inherits the type's again. |
A model upload takes keep_ports=1 with ports_bounds (the new model's
upright size, JSON [w, h, d]) to keep the mapping; the server keeps it only
when the proportions match. Each device's face-ports/ answer lists the
mapped ports under model, resolved to the device's real components like
photo markers, with their p and n and an interface's untagged VLAN.
Device bays (chassis nesting)¶
A parent chassis (blade enclosure, FEX parent) declares device bays on its type (Components → Device bays) and sets Subdevice role: parent; blade/child models set child (usually 0U). Devices of the parent type get concrete bays stamped, and the device page's Hardware tab shows a Device bays table - Install… puts a whole child device in a bay (it keeps its own ports, IPs and lifecycle; the bay records where it physically lives). Unlike modules, a bay's occupant is an independent device.
Types can also tick Exclude from utilisation (blanking panels, cable management): they render in elevations but don't count toward the rack's used-units number.
Inventory items¶
Inventory items are serial-tracked physical parts that aren't cabled components - disks, CPUs, RAM, PSUs, fans, discrete SFPs. Templates on the device type (Components → Inventory) stamp onto new devices; on the device page's Hardware tab you can add/edit parts with manufacturer, part ID, serial and asset tag, and nest them one level (a fan tray containing fans). Roles are just tags - no pre-filled role catalog, per the zero-data rule.
Each part also carries its hardware identity and health:
- Kind - what the part is: Disk, CPU, RAM, PSU, Fan, GPU, Controller, Transceiver, or Other (the default for pre-existing parts).
- The form follows the kind. A disk offers media, speed and capacity; RAM offers speed (DDR grade / MT/s) and size; a CPU offers its clock and nothing about capacity; a fan its RPM; a PSU none of the three. Every kind used to wear the disk outfit - a CPU offering "7200 RPM" and a capacity in GB. Fields a kind doesn't show keep their stored value, so editing a BMC-synced part never wipes facts Redfish wrote.
- Slot - where the part sits: Socket 1, DIMM A1, Bay 3, PSU 2. Optional, free text, shown as its own column and on the hardware sheet.
- Cores (CPUs) - so the Hardware tab and the hardware sheet can add the box up: total cores across sockets, total memory, total storage, each with the count, size, clock or grade most parts share underneath.
- Add another on the Add part dialog saves the part and keeps the dialog open with the next name and slot in the sequence (CPU1 → CPU2, DIMM A1 → DIMM A2) and the serial and asset tag cleared.
- Media (disks) - NVMe, SSD (SATA/SAS), HDD, or Tape.
- Capacity with a unit picker (KB → PB; stored in bytes, so it's backwards- and future-proof).
- Speed - a dropdown of the common industry values for the part in front of you: spindle rates for an HDD (5400/7200/10K/15K RPM), the bus for flash (SATA 6Gb/s, SAS 12/24Gb/s, PCIe 3.0–5.0 x4), memory grades for RAM (DDR4-3200, DDR5-5600), LTO generations for tape. The field stays free text, so any vendor's wording still fits - the list is there to keep eight disks from being recorded eight different ways.
- Status - the part's lifecycle/health from the shared status catalog: every tenant gets Active / Planned / Failed / Spare for inventory items (extensible like any other status). Marking a disk Failed colours it red wherever the part is shown.
Templates carry kind/media/capacity/speed too, so a device type modelled with
eight Bay {position} NVMe templates stamps ready-described disks onto every
new device.
Bulk-editing parts¶
On the device's Hardware tab, tick the checkbox on one or more parts (the header checkbox selects all) - a bulk bar floats up:
- Edit opens a keep/set dialog: anything left on Keep current is untouched; set Status (mark eight disks Failed in one go), Kind, Media, Capacity (value + KB…PB unit), Speed, Part ID, Description, or add/remove tags - applied to every selected part.
- Rename does find/replace across the selected names (regex optional), with a live preview.
- Clone duplicates the selected parts under new names.
- Delete removes them after a confirmation.
The same bulk bar (and the same keyboard-free flow) is used on the interface and port tables, so one habit covers every component list.
Module types¶
A module type is a pluggable hardware model - a line card, uplink module,
or PSU sled (e.g. a Cisco C9300-NM-8X). It lives under DCIM → Catalog →
Module types and carries its own interface templates, whose names may use the
{module} token: when a module is installed into a device's bay, the
token resolves to the bay's position (TenGigabitEthernet1/{module}/1 in
bay position 1 → …1/1/1), and the {position} stack
token still applies after.
The [1-24] range shorthand works here too: A[1-24] or
TenGigabitEthernet1/{module}/[1-8] adds one template per port in a single
add, from the dialog or the API. A range written with curly braces
({1-24}) is refused rather than stored literally. A module type records its
own cooling method (cooling_method) too; it is a fact about the module
and does not change its host device's.
The workflow:
- Give a device type module bay templates (Components → Module bays) - each bay names the slot and sets its position. Optionally pick a Default module on a bay template: a module of that type is pre-installed when the bay is stamped onto a new device, and seated into an empty matching bay when you sync from type on an existing device (see below).
- Devices of the type get concrete bays stamped at creation, with any default modules already seated.
- On the device page's Hardware tab, Install… a module type into an empty bay - its interfaces appear on the device (and its faceplate) instantly. Remove takes exactly those interfaces away again.
A module owns the interfaces it creates (module_id on each interface in
the API; null for the device's own ports). Ownership survives renaming the
interface, and decides what goes when the module does:
- Install refuses a module whose interface names the device already uses - its own ports or another module's. Rename or remove the clashing interface first; nothing is adopted.
- Remove deletes the module's own interfaces and nothing else, with the usual interface delete rules: a cable left with no port on that end is removed (see Cabling) and IP addresses stay, unassigned.
- Deleting a module bay removes its module the same way, as does deleting the device.
- Moving a module to another bay, or changing its type, keeps the interfaces that still correspond and renames them in place, so cables, IP addresses, VLANs, LAG membership, MACs, tags, custom fields, descriptions and the journal stay with them. Only ports the new type lacks are removed and only its new ports are created. See Re-stamping a module.
- Moving a module to another device removes its interfaces and creates them again on the new device.
- Copies are your own: a bulk-cloned interface (a sub-interface made from a module port, say) has no module and survives removing the module. Imports cannot set or clear an interface's module either.
- A default module whose interface names clash with the device's is not seated.
Modules installed before 0.17.2 had no recorded owner. The upgrade marks an existing interface as the module's only when that is unambiguous: its name is one the module's templates render to, no other module on the device renders it, the device type does not define it (as a template or a faceplate or photo marker), and it was created no earlier than the module. Anything else stays the device's own - it survives removing the module, and you delete it by hand if it was the module's.
Re-stamping a module¶
Each module interface remembers the template it was stamped from. On a bay
move or type change (PATCH /api/modules/<id>/ with module_bay_id or
module_type_id), every interface is matched to its successor:
- Same type, new bay: each template continues as itself. The interface
is renamed to the template's new rendering (
Te1/1/1→Te1/2/1). - Different type: templates with the same name pattern pair first
(
Te1/{module}/1in both types), then the rest pair by position in template order where the media type matches. A paired interface takes the new type's media type. - An interface you renamed keeps your name. One whose template can no longer be traced (renamed before 0.18, or its template deleted) is left as it is.
Removing an interface that carries a cable or an IP address needs
"confirm_remove": true in the request. Without it the change is refused
with a confirm_remove error naming those interfaces, and nothing changes.
With it, the usual interface delete rules apply. A name clash with an
interface the module does not own refuses the change. Either way the
module stays as it was.
The response carries what happened under interfaces:
kept, renamed ({"from", "to"}), created and removed.
A default module only decides what's pre-seated - it never locks a bay. Sync-from-type fills empty matching bays with the default but never overwrites a module you installed (or deliberately left out until the next sync), so hand-placed hardware is safe.
Module types have their own Faceplate tab - the same drag-and-drop
builder device types get, with the module's interface templates as the
palette. When a module with a saved faceplate is installed in a device, its
layout is composed into the device's render - at the bay's placeholder if
the device type's layout places that bay, otherwise appended ({module} in
slot names resolves to the bay position, so the cages light up with the real
interfaces' state). Editing a module type's faceplate refreshes every device
that has one of its modules installed.
Module-type YAMLs from the devicetype-library import through the same
Import from library dialog - they're auto-detected (no u_height), so
you can paste module-types/... links right next to device types. The Module
types page opens it too, from its own Import from library; a /tree/ link to
module-types/<Manufacturer> imports that manufacturer's module types in the
background.
Device roles¶
A role classifies what a device does - access switch, distribution, core, firewall, load balancer. Roles carry a color so devices group visually in lists, and an optional icon shown in the role's badge - in the device and role lists, on the role's page and on maps. On a floor plan the role's icon is the fallback for a device whose type and own record name none (see Icons when zoomed out). Roles also accept custom fields (target Device roles) - for example a service tier or an escalation team.
Platforms¶
A platform is the operating system / NOS a device or virtual machine runs - IOS-XE, JunOS, PAN-OS, Cumulus. Platforms are handy for filtering and for configuration rendering.
A platform also carries a Target version and a Version pattern - the
regular expression that reads the running version out of SNMP sysDescr
and Oxidized configurations for devices and VMs on it; see Software
target and Version
pattern. Its License is
the OS's SPDX licence expression (license in the API and import), reported
by the SBOM. Its Package URL and CPE
(purl_template, cpe_template) are templates for the OS component's
purl and cpe, filled in with the host's software version; see Package
URLs and CPEs.
A platform's page has a Devices tab and a Virtual machines tab, each
listing what runs it; the API gives both counts (device_count, vm_count).
Like every catalog count, they count only the devices and virtual machines
you may view, so a site-limited user's tab number matches the table under it.
Editing and deleting platforms in bulk¶
Tick rows in the Platforms list and a bar floats up with Edit and Delete (each shown only with the change or delete permission on platforms).
- Edit sets the Group, Manufacturer, Config template, Target version and Description of every ticked platform, and adds or removes tags. Only the fields you tick are written; each platform gets its own change log entry. The version pattern stays a one-at-a-time edit.
- Delete asks first. The dialog says how many platforms go, what goes with them (an end-of-life mapping, a monitoring policy scoped to the platform), and which are kept because something still uses them: a platform any device or virtual machine runs (counted across the whole tenant, not only what you can see), or one a device profile names. Only the free platforms are deleted, the same rule a single delete follows.
The endpoints are POST /api/platforms/bulk-delete/ ({"ids": [...]}, add
"dry_run": true for the preview; needs delete), POST
/api/platforms/bulk-update/ ({"ids": [...], "fields": {...}} with
group_id, manufacturer_id, config_template_id, target_version,
description, add_tag_ids, remove_tag_ids; needs change) and GET
/api/platforms/bulk-edit-fields/ - see Bulk
calls. Ids from another tenant, or outside your
permissions, are left out; a group, manufacturer or template from another
tenant is a 400.
Platform groups and the effective platform¶
Platform groups (their own sidebar page) organise platforms into families - "Windows", "Linux", "Others" - and can nest via an optional parent group (e.g. "Debian family" under "Linux"). A platform optionally points at one group. Groups are catalog objects like the rest: tenant-scoped, empty until you define them, and deletable only once no platform references them.
A device type can also carry an optional platform - the OS the hardware generically runs. That gives every device an effective platform:
- the device's own platform, when set - e.g. the type says Windows (generic) but this box runs Windows 11 22H2;
- otherwise the type's platform (the fallback).
The device's stored platform field is untouched - the fallback is derived and
read-only (effective_platform on the device API). The device Overview shows
the inherited value with a (from type) hint, so you can tell an explicit
platform from an inherited one at a glance.
Lifecycle (EoS / EoL)¶
Device types and platforms both carry optional vendor lifecycle dates - released, end of sale, end of security updates, end of support - which drive a lifetime progress bar and an at-risk badge across the catalog, the devices table, and each device's overview. See Hardware & OS lifecycle.
All five are yours to define - Danbyte ships none of them, so your catalog contains exactly the vendors, models, roles, platforms, and platform groups your network uses.