# 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

```yaml
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

```bash
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.

```bash
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.

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

Look up IDs first:

```bash
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:

```bash
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

- `internal/agent/tool_netbox.go`
- `internal/config/config_types.go`
- `config.yaml.example`