Skip to content

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 airflow list of GET /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 .yaml files in the library (one per line - regular blob links 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 .yaml files.

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 .mtl materials aren't carried).
  • A .gltf that refers to separate .bin or texture files is refused - upload the .glb instead.
  • 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.

  1. 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.
  2. Unzip it if it came as a .zip, and upload the .step or .stl on the type's 3D model card.
  3. 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.
  4. 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, which gltfpack -c writes 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_webp and EXT_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_intakes and cooling_outflows, an outflow naming its intake
  • 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/* to 2/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:

  1. 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).
  2. Devices of the type get concrete bays stamped at creation, with any default modules already seated.
  3. 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}/1 in 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.