Import from NetBox¶

Migrate an existing NetBox instance into Danbyte over NetBox's REST API. The importer pulls every supported object type, resolves cross-references, and writes them into one Danbyte tenant. Re-running is safe: existing objects are skipped unless you opt into updating them.

There are two ways to run it — the UI (best for most migrations) and the CLI (for very large or air-gapped moves).

From the UI¶

Import → NetBox (tenant admins only). The import runs in the background on the job queue, so you can watch it progress and leave the page.

1. Connect — paste your NetBox URL and a (read-only is fine) API token. Allow self-signed certificate covers an internal NetBox with a private CA. Test connection shows the NetBox version and a count of the big object types, so you can see what's about to be pulled.
2. Options — Dry run (on by default) fetches and builds the whole graph in a transaction that's rolled back at the end: real counts, nothing saved. Update existing objects re-applies NetBox values to objects already in Danbyte — it overwrites local edits, so it's off by default.
3. Run — a progress bar tracks the current step (e.g. devices · 12/58), and a live table fills in per type: fetched / new / existing / updated / failed / skipped. While a large type is being pulled you'll see a live fetching N rows… counter, so a slow multi-page fetch reads as working, not stuck. The import runs on the default job queue so it starts promptly.
4. Result — totals, any notes, and a table of failures (one row per object that couldn't be created, with the reason). After a clean dry run, a Run for real button appears.
5. Recent imports lists past runs; click one to re-open its report.

Failed vs skipped. Failed means Danbyte tried to create the object and couldn't — those rows appear in the failures table with the exact error. Skipped means the importer deliberately left the row out: its parent didn't make it into the import (e.g. a front port whose rear port is missing), or there's nothing to create (a planned NetBox cable with no terminations yet). Each skip reason is tallied in the notes with a few sample NetBox IDs, so an all-skipped type is diagnosable straight from the report. If a whole endpoint couldn't be fetched (timeout, TLS, permissions), that surfaces both as a note and as a failure row for the type — it never disappears silently.

From the CLI¶

For a very large instance, or one only reachable from the server's shell:

cd /opt/danbyte/danbyte
sudo -u danbyte .venv/bin/python manage.py import_netbox \
    --url https://netbox.example.com \
    --token <NETBOX_API_TOKEN> \
    --tenant default \
    --report netbox-import.json

How it works¶

• One tenant. Everything lands in a single Danbyte tenant (a hard isolation boundary). NetBox's own soft tenant label is kept on each object as custom_fields.netbox_tenant, and its NetBox id as custom_fields.netbox_id.
• Dependency order. Catalogs → geography → power → IPAM → devices → components → virtualization → IP addresses → services → cables → circuits → contacts → floor plans (netbox-map plugin, if present), then finalize passes that wire the relations which form cycles (interface LAG/parent/bridge, device/VM primary IP, virtual-chassis).
• Idempotent. Each object is matched on a natural key (cables on an existing termination); a re-run only fills gaps and counts the rest as existed — or, with update existing, re-applies NetBox's values and counts them updated.
• Resilient. Each object is its own savepoint. One bad row is recorded (type, name, NetBox id, reason) and the import continues.

Prefix requirement. Danbyte requires every IP to belong to a prefix. For each NetBox IP the importer attaches it to the most-specific imported prefix that contains it; if none exists it auto-creates one from the IP's own mask (tagged custom_fields.source = "netbox-import (auto)").

Coverage¶

Imported — manufacturers, platforms, device/rack/IP roles, RIRs, cluster types/groups, circuit types, providers & networks, contact roles/groups, route targets, VRFs, regions, sites, locations, aggregates, ASNs, racks, power panels & feeds, device types, module types, component templates, clusters, VLAN groups, VLANs, prefixes, IP ranges, devices, virtual chassis, module bays, modules, device bays, inventory items, interfaces (with LAG / parent / bridge), console + console-server ports, power ports + outlets, rear / front ports, MAC addresses, virtual machines & interfaces, IP addresses, services & templates, FHRP groups + assignments, cables (+ terminations), circuits (+ terminations), contacts (+ assignments), and tags + custom-field values on everything that carries them.

Floor plans (netbox-map plugin). If the source NetBox runs the netbox-map plugin, its floorplans and tiles come along too: plans map to Danbyte floor plans (a plan hung directly on a NetBox site lands in a per-site "Imported floor plans" location), tile positions/sizes/labels are preserved, device- and rack-linked tiles resolve to the imported objects, floorplan_link tiles become nested-plan navigation, camera tiles keep their field-of-view cone, and each distinct plugin tile_type is minted as a tenant floor tile type (with a sensible icon). Background images are downloaded on real runs (skipped during a dry run — file writes can't roll back). A NetBox without the plugin just gets a note; nothing fails.

Not imported yet (Danbyte has the model, NetBox has the data — planned): tunnels & IPSec profiles, L2VPNs, wireless LANs, config contexts / templates, image attachments, journal entries, webhooks. A cable to a NetBox circuit termination is skipped (Danbyte cables don't terminate on circuits).

No Danbyte equivalent (skipped by design): site groups, rack reservations, 1:1 NAT links, VLAN translation, virtual disks, custom links, saved filters, data sources / GitOps sync, scripts, event-rule DSLs.

Reading the report¶

Every run — UI or CLI — produces the same per-type breakdown:

NetBox → Danbyte import  (tenant: default)
──────────────────────────────────────────────────────────────
TYPE                    FETCH    NEW  EXIST    UPD   FAIL
manufacturers              12     12      0      0      0
sites                       4      4      0      0      0
devices                    87     85      0      0      2
ip_addresses              512    509      0      0      3
──────────────────────────────────────────────────────────────
TOTAL                     ...

Failures (5):
  ✗ [devices] core-sw-01 (nb#123): <reason>
  …

Re-running after fixing the source data (or a Danbyte bug) picks up only the rows that didn't make it the first time.