🏠 Home ← Docs Index
Open Beta 📖 Interactive Reader Raw .md llms.txt

NetBox IPAM And DCIM Integration

GoClaw integrates with NetBox through the netbox tool. It can read IPAM/DCIM inventory, allocate addresses, inspect rack layout, add journal entries, and create or update records when write access is enabled.

Configuration

tools:
  observability:
    netbox:
      prod:
        url: "https://netbox.example.com"
        token: "${secret:NETBOX_TOKEN}"
        allow_write: false
        description: "Production IPAM/DCIM"
      dev:
        url: "http://netbox-dev:8080"
        token: "${secret:NETBOX_DEV_TOKEN}"
        allow_write: true
        insecure: true
        description: "Development NetBox"

allow_write: false is the safe default. Keep production instances read-only unless the agent is explicitly allowed to modify NetBox.

The NetBox host does not need to be on tools.http.allow: like the other observability tools, netbox may reach its own url, while tools.http.deny still applies. insecure: true skips TLS certificate verification; use it only for a development instance.

Actions

Action Type Notes
list Read Search resources with filters
get Read Fetch one resource by id
rack-elevation Read Render rack elevation; requires resource_type=racks and id
available-ips Read; Write with data List free IPs in a prefix; requires id. With data, allocates one, which needs allow_write: true
available-prefixes Read; Write with data List available child prefixes; requires id. With data, allocates one, which needs allow_write: true
available-vlans Read; Write with data List available VLAN IDs in a VLAN group; requires id. With data, allocates one, which needs allow_write: true
create Write Requires data and allow_write: true
bulk-create Write Requires bulk_data and allow_write: true
update Write Full replacement; requires id, data, and allow_write: true
patch Write Partial update; requires id, data, and allow_write: true
delete Write Requires id and allow_write: true
journal-add Write Adds a journal entry; requires data and allow_write: true
cable-connect Write Creates a cable; requires data and allow_write: true

Resource Types

Area Resource types
DCIM sites, regions, locations, racks, rack-types, rack-roles, rack-reservations, devices, device-types, device-roles, platforms, manufacturers, interfaces, cables, power-panels, power-feeds, inventory-items, virtual-chassis, modules
IPAM ip-addresses, prefixes, ip-ranges, vlans, vlan-groups, vrfs, aggregates, rirs, asns, asn-ranges, roles, services
Virtualization virtual-machines, clusters, cluster-types, cluster-groups
Extras tags, custom-fields, webhooks, journals

The tool also normalizes common aliases such as "server" to devices and "vm" to virtual-machines.

Read Examples

goclaw tools exec netbox action=list resource_type=devices filters='{"status":"active","limit":50}'
goclaw tools exec netbox action=list resource_type=racks filters='{"site":"dc1"}'
goclaw tools exec netbox action=list resource_type=ip-addresses filters='{"address":"10.0.0.50/24"}'
goclaw tools exec netbox action=get resource_type=prefixes id=5
goclaw tools exec netbox action=available-ips resource_type=prefixes id=5
goclaw tools exec netbox action=available-prefixes resource_type=prefixes id=5
goclaw tools exec netbox action=available-vlans resource_type=vlan-groups id=2
goclaw tools exec netbox action=rack-elevation resource_type=racks id=3

Write Examples

These require allow_write: true on the selected instance.

goclaw tools exec netbox action=create resource_type=ip-addresses data='{"address":"10.0.0.55/24","status":"active","description":"prod-web-04 mgmt"}'
goclaw tools exec netbox action=create resource_type=devices data='{"name":"prod-db-04","device_type":5,"device_role":3,"site":1,"status":"staged"}'
goclaw tools exec netbox action=patch resource_type=devices id=42 data='{"status":"offline"}'
goclaw tools exec netbox action=journal-add resource_type=journals data='{"assigned_object_type":"dcim.device","assigned_object_id":42,"comments":"Maintenance completed"}'
goclaw tools exec netbox action=cable-connect resource_type=cables data='{"a_terminations":[{"object_type":"dcim.interface","object_id":1}],"b_terminations":[{"object_type":"dcim.interface","object_id":2}]}'

Filter Rules

Pass filters as an object, not as a JSON-encoded string when the LLM calls the tool. CLI examples quote JSON only because the shell needs it.

Useful filters:

Resource Filters
devices status, site, role, rack, q, tenant, tag, limit, offset
ip-addresses address, status, device, tenant, tag, limit, offset
prefixes within, site, vrf, tenant, tag, limit, offset
vlans vid, site, tenant, tag, limit, offset
virtual-machines cluster, status, q, tenant, tag, limit, offset

Foreign Key Rules

NetBox foreign keys such as tenant, site, rack, device_type, and device_role usually require integer IDs in write payloads, not display labels.

Wrong: {"site":"Production"}
Right: {"site":1}

Look up IDs first:

goclaw tools exec netbox action=list resource_type=sites filters='{"q":"Production"}'
goclaw tools exec netbox action=list resource_type=device-types filters='{"q":"PowerEdge R650"}'

Server Registration Workflow

  1. Find the site, rack, device type, and role IDs.
  2. Find an available management IP.
  3. Create the device.
  4. Create the IP address.
  5. Attach the IP to an interface if needed.
  6. Add a journal entry for traceability.

Example:

goclaw tools exec netbox action=list resource_type=racks filters='{"site":"dc1"}'
goclaw tools exec netbox action=list resource_type=device-types filters='{"q":"PowerEdge R650"}'
goclaw tools exec netbox action=available-ips resource_type=prefixes id=2
goclaw tools exec netbox action=create resource_type=devices data='{"name":"prod-db-04","device_type":8,"device_role":3,"site":1,"rack":3,"status":"staged"}'
goclaw tools exec netbox action=create resource_type=ip-addresses data='{"address":"10.0.0.56/24","status":"active","description":"prod-db-04 mgmt"}'

Implementation Files