From your source of truth
Drawbridge has no connector for NetBox and no reader for your lab tool, and needs neither: each of them can already write something the importer reads — Graphviz DOT, a containerlab topology or a draw.io file. This page has one recipe per tool. Every sample on it is real — the tool's own output for a small invented network, or the file it was given — and a test runs each one through the same importer the app uses, so what the page says arrives is what arrives.
| Source | What it writes | What arrives |
|---|---|---|
| NetBox | DOT, through an export template you add once | Every cabled device, typed by its role; both port names on every cable, with speed, medium, length and label; management address, serial, model |
| netlab | a containerlab topology, or DOT with any provider | Devices typed by what they run, port names and management addresses — or, through DOT, the kinds you give its groups |
| containerlab | its own topology file, read as it is | Devices typed by kind, port names, management addresses, groups as zones |
| nrx | a containerlab topology built from NetBox | Devices and cables, with the lab's port names |
| NetBox Topology Views | a draw.io file | The plugin's own picture, opened as a drawing |
Handing the text over
Every recipe ends in a file of text, and there are three ways in — the same importer and the same drawing whichever you pick:
- The command line draws it with no window:
Drawbridge --import site-a.gv --export site-a.drawio, or.svg,.pngand the rest of the list in Code in, image out.Drawbridgestands for the installed binary, which lives in a different place on each platform. - Import in the app: paste the text, read the preview — the format it found, the devices and cables it counted, any line it could not read — and press Import.
- An import link carries the text inside the address, behind the
#, so the browser that opens it does the drawing and no server ever sees the topology; Four ways in shows how to build one.
Nothing on this page needs our server. The hosted API in Code in, image out takes the same text if you want it, and only then.
NetBox
NetBox writes any list it holds through an export template: a Jinja2 template you add once and NetBox renders on request. The one below hangs off cables, because the cables are the topology — every device a cable reaches comes with it. It was written and run on NetBox 4.7.5.
Add the template
In NetBox, open Customization › Export Templates and press Add:
- Name:
drawbridge— the name you ask for it by. - Object types: DCIM › Cable.
- Template code: the template below, exactly as it is.
- MIME type:
text/vnd.graphviz, and File extension:gv.
{#- Drawbridge: NetBox cables to Graphviz DOT. Attach to DCIM > Cable. -#}
{#- Role slug to Drawbridge kind. Add your own roles here. -#}
{%- set kinds = {
'router': 'router', 'edge-router': 'router', 'core-router': 'router',
'firewall': 'firewall',
'core-switch': 'l3-switch', 'distribution-switch': 'l3-switch',
'spine': 'l3-switch', 'leaf': 'l3-switch',
'access-switch': 'switch', 'switch': 'switch',
'server': 'server', 'hypervisor': 'server', 'storage': 'storage',
'access-point': 'wifi-ap', 'wireless-ap': 'wifi-ap',
'wireless-controller': 'wlc', 'load-balancer': 'load-balancer',
'console-server': 'console-server', 'patch-panel': 'patch-panel',
'pdu': 'pdu', 'ups': 'ups'
} -%}
{#- Higher tiers are drawn above lower ones. -#}
{%- set tiers = {'internet': 0, 'cloud': 0, 'router': 1, 'firewall': 2,
'load-balancer': 2, 'l3-switch': 3, 'switch': 4} -%}
{%- macro kind(d) -%}
{{ d.cf.get('drawbridge_kind') or kinds.get(d.role.slug, d.role.slug) }}
{%- endmacro -%}
{%- macro q(s) -%}
"{{ s|string|replace('\\', '\\\\')|replace('"', '\\"') }}"
{%- endmacro -%}
{%- macro media(t) -%}
{%- if t.startswith('cat') -%}rj45
{%- elif t.startswith('dac') -%}dac
{%- elif t.startswith('aoc') -%}aoc
{%- elif t.startswith('mmf') -%}mmf
{%- elif t.startswith('smf') -%}smf
{%- endif -%}
{%- endmacro -%}
{%- set ns = namespace(ids=[], devices=[]) -%}
{%- for cable in queryset -%}
{%- for t in cable.a_terminations + cable.b_terminations -%}
{%- if t.device and t.device.pk not in ns.ids -%}
{%- set ns.ids = ns.ids + [t.device.pk] -%}
{%- set ns.devices = ns.devices + [t.device] -%}
{%- endif -%}
{%- endfor -%}
{%- endfor -%}
digraph netbox {
{%- for d in ns.devices %}
nb{{ d.pk }} [kind={{ q(kind(d)) }}, label={{ q(d.name or d.device_type.model ~ ' ' ~ d.pk) }}
{%- if d.primary_ip4 %}, mgmtIp={{ q(d.primary_ip4.address.ip) }}{% endif %}
{%- if d.serial %}, serial={{ q(d.serial) }}{% endif %}, model={{ q(d.device_type.model) }}
{%- if d.site %}, location={{ q(d.site.name ~ (' / ' ~ d.rack.name if d.rack else '')) }}{% endif %}]
{%- endfor %}
{% for cable in queryset %}
{%- set a = cable.a_terminations|first %}
{%- set b = cable.b_terminations|first %}
{%- if a and b and a.device and b.device %}
{%- set ta = tiers.get(kind(a.device), 5) %}
{%- set tb = tiers.get(kind(b.device), 5) %}
{%- if ta > tb %}{% set a, b = b, a %}{% endif %}
{%- set kbps = a.speed or b.speed %}
{%- set medium = media(cable.type or '') %}
nb{{ a.device.pk }} -> nb{{ b.device.pk }} [id="cable-{{ cable.pk }}", taillabel={{ q(a.name) }}, headlabel={{ q(b.name) }}
{%- if kbps %}, speed="{{ kbps // 1000000 ~ 'G' if kbps >= 1000000 else kbps // 1000 ~ 'M' }}"{% endif %}
{%- if medium %}, medium={{ medium }}{% endif %}
{%- if cable.label %}, label={{ q(cable.label) }}{% endif %}
{%- if cable.length %}, length={{ q('%g %s'|format(cable.length|float, cable.length_unit or '')) }}{% endif %}]
{%- if ta == tb and ta < 4 %}
{rank=same; nb{{ a.device.pk }} nb{{ b.device.pk }}}
{%- endif %}
{%- endif %}
{%- endfor %}
}
What it does, and where to change it:
- A kind from each device's role.
kindsmaps a role's slug to a Drawbridge kind — without akind=every device would arrive as the same plain box, which is the whole reason to use this template rather than write your own from scratch. A role yours calls something else goes into the map as one more pair,'dmz-firewall': 'firewall'. A role the map does not list is sent as its own slug, and the import reports it as an unknown kind with the nearest real one, so a missing pair shows up rather than hiding. The DOT reference lists every kind. - A kind for one device. When one device should not look like the rest of its role — the web server among the application servers — add a text custom field named
drawbridge_kindto DCIM › Device and fill it in on that device. Its value wins over the role. The field is optional: without it, the role decides. - Arrows down the tiers. In DOT the arrows decide which device is drawn above which, and NetBox's A and B ends say nothing about that. So the template points every cable from the higher device to the lower, by kind: routers, then firewalls and load balancers, then L3 switches, then switches, then everything else. Two devices of the same tier above the access switches — an HA firewall pair, a core pair — are declared peers (
rank=same) and stand side by side instead of one under the other.tiersis where to change the order. - Both port names on every cable, as
taillabel=andheadlabel=, which carry any interface name as NetBox writes it —GigabitEthernet1/0/49included. - What the cable is. The speed comes from the interface's speed field, the medium from the cable's type (copper, DAC, AOC, multimode or single-mode fibre), and the length and label from the cable. Each is left out when NetBox has nothing to say.
- What the device is. Its primary IPv4 address becomes the management address, and its serial, model, site and rack come along as asset data.
- Every cable once, with NetBox's own cable number as its
id=, so two cables between the same two devices stay two. Devices are named by NetBox's number too (nb12) and labelled with their name, so two devices that share a name in different sites stay two, and a device with no name still draws, as its model and number.
A cable to a circuit or to a power feed has no device on its far end, and the template leaves it out; the device on its near end is drawn all the same.
Render it
From a script, ask NetBox's API for the cable list with export= and the template's name. The export is the whole filtered list, never one page of it, and any filter the cable list takes narrows it — site= for a site, rack_id= for a rack, device= for one device and its neighbours:
curl -fsS -H "Authorization: Bearer $NETBOX_TOKEN" \
"https://netbox.example.net/api/dcim/cables/?site=site-a&export=drawbridge" > site-a.gv
Drawbridge --import site-a.gv --export site-a.drawio
Bearer is for the API tokens NetBox has had since 4.5 (nbt_…); a legacy token goes as Authorization: Token ….
By hand, open DCIM › Cables in NetBox, filter it, choose Export › drawbridge, and paste what it gives you into Import.
What arrives
For an invented site — an edge router, an HA firewall pair, two core switches, two access switches, a server and an access point — NetBox 4.7.5 rendered this:
digraph netbox {
nb1 [kind="router", label="rtr-edge-01", mgmtIp="192.0.2.1", serial="SN-RTR-0001", model="ER-1000", location="Site A / R01"]
nb2 [kind="firewall", label="fw-edge-01", mgmtIp="192.0.2.11", serial="SN-FW-0001", model="FW-200", location="Site A / R01"]
nb3 [kind="firewall", label="fw-edge-02", mgmtIp="192.0.2.12", serial="SN-FW-0002", model="FW-200", location="Site A / R01"]
nb4 [kind="l3-switch", label="core-sw-01", mgmtIp="192.0.2.21", serial="SN-CS-0001", model="CS-4800", location="Site A / R01"]
nb5 [kind="l3-switch", label="core-sw-02", mgmtIp="192.0.2.22", serial="SN-CS-0002", model="CS-4800", location="Site A / R01"]
nb6 [kind="switch", label="acc-sw-01", serial="SN-AS-0001", model="AS-2400", location="Site A"]
nb7 [kind="switch", label="acc-sw-02", serial="SN-AS-0002", model="AS-2400", location="Site A"]
nb8 [kind="web-server", label="srv-app-01", serial="SN-SRV-0001", model="SRV-1U", location="Site A / R01"]
nb9 [kind="wifi-ap", label="ap-lobby-01", model="AP-100", location="Site A"]
nb1 -> nb2 [id="cable-1", taillabel="ge-0/0/1", headlabel="port1", speed="10G", medium=smf, length="3 m"]
nb1 -> nb3 [id="cable-2", taillabel="ge-0/0/2", headlabel="port1", speed="10G", medium=smf, length="3 m"]
nb2 -> nb3 [id="cable-3", taillabel="ha1", headlabel="ha1", speed="1G", medium=rj45, label="HA"]
{rank=same; nb2 nb3}
nb2 -> nb4 [id="cable-4", taillabel="port2", headlabel="Ethernet1/1", speed="10G", medium=dac]
nb3 -> nb5 [id="cable-5", taillabel="port2", headlabel="Ethernet1/1", speed="10G", medium=dac]
nb4 -> nb5 [id="cable-6", taillabel="Ethernet1/49", headlabel="Ethernet1/49", speed="10G", medium=dac, label="peer-link"]
{rank=same; nb4 nb5}
nb4 -> nb6 [id="cable-7", taillabel="Ethernet1/2", headlabel="GigabitEthernet1/0/49", speed="10G", medium=mmf, length="25 m"]
nb5 -> nb7 [id="cable-8", taillabel="Ethernet1/2", headlabel="GigabitEthernet1/0/49", speed="10G", medium=mmf, length="25 m"]
nb6 -> nb8 [id="cable-9", taillabel="GigabitEthernet1/0/1", headlabel="eth0", speed="1G", medium=rj45]
nb7 -> nb9 [id="cable-10", taillabel="GigabitEthernet1/0/2", headlabel="eth0", speed="1G", medium=rj45]
}
Imported, that is nine devices and ten cables with nothing reported: the router on top, the firewall pair side by side under it, the core pair under them, then the access switches, the server and the access point. Two of those cables were entered in NetBox with the lower device on the A end, and they arrive pointing down all the same. The server is a web server because its drawbridge_kind field says so; its role says server.
netlab
netlab hands its lab over in one of two ways, and the first is the richer.
When containerlab runs the lab
With provider: clab, netlab create — and netlab up, which runs it — writes clab.yml, containerlab's own topology file. Import that:
netlab create
Drawbridge --import clab.yml --export fabric.drawio
Each device's kind comes from what it runs — cEOS draws as an L3 switch, a Linux host as a server — each cable carries the interface names netlab gave it (et1, eth1), the management addresses come along, and each netlab group becomes a zone. One thing to tidy afterwards: netlab puts its Linux hosts in two groups of its own as well, and the zone around them arrives named servers,netlab_no_reload,netlab_no_collect — rename it.
With any provider, through DOT
netlab create -o graph writes graph.dot for any provider, with no lab running. netlab copies a node's graph.format settings into the DOT as they are, so give each group its kind there and every device arrives typed:
groups:
spines:
members: [spine1, spine2]
graph.format.kind: l3-switch
leaves:
members: [leaf1, leaf2]
graph.format.kind: switch
servers:
members: [srv1, srv2]
device: linux
graph.format.kind: server
netlab create -o graph
Drawbridge --import graph.dot --export fabric.svg
netlab 26.10 wrote each spine like this:
"spine1" [
kind="l3-switch"
label="spine1 [eos]\n192.0.2.1/32"
]
The label is netlab's own — the name, the device in brackets and the loopback address on a second line — and that is the name the device arrives with. netlab writes an undirected graph, so the tiers follow the order of the links: list them top-down, spines to leaves to hosts. It writes no interface names, so the cables arrive without ports; when you want them, use clab.yml.
containerlab
A containerlab topology file is already something to import, with no lab running:
Drawbridge --import fabric.clab.yml --export fabric.svg
Each node's kind decides its picture — SR Linux and cEOS as L3 switches, SR OS and the vMX as routers, linux as a server — each link's endpoints become the port names at its two ends, mgmt-ipv4 becomes the management address and group becomes a zone.
containerlab graph --dot writes a DOT file as well, and it is the poorer input. It carries no interface names, and it puts each node's kind where only Graphviz reads it, as a caption beside the box:
leaf2 [ color=red, fillcolor=red, group=leaf, label=leaf2, style=filled, xlabel=arista_ceos ];
So every device arrives as a plain box and every cable without ports. Import the topology file that command reads instead.
nrx
nrx reads a site out of NetBox and writes a containerlab topology, so what it writes imports as one:
nrx --api https://netbox.example.net --site "Site A" --output clab --noconfigs
Drawbridge --import "Site A.clab.yaml" --export site-a.drawio
It is built to start a lab, and it shows. A device's kind comes from its platform through nrx's platform map, not from its role, and a device with no platform in that map becomes a Linux container — which draws as a server, firewalls and access points included. Interfaces are renamed to the lab's eth1, eth2. And the topology carries nrx's own graphite viewer as one more node, with no cables, which you can delete. For a drawing of the site, the export template above keeps NetBox's names and roles; nrx is the one to reach for when you are building the lab from NetBox anyway. Tried with nrx 0.9.0 against the same NetBox.
NetBox Topology Views
The NetBox Topology Views plugin draws a site's devices inside NetBox and can export what it drew as a draw.io file. Drawbridge opens that the way it opens any draw.io file — as draw.io draws it, positions kept, nothing laid out again; see What you can open. Use it when you want the plugin's arrangement, and the export template when you want Drawbridge's.